@harborppm/cli 0.57.0 → 0.59.0

package/lib/cli.mjs

@@ -39,6 +39,7 @@ import {
   lifeboatsText,
   followedText,
   soundingsText,
+  ashoreText,
   voyageText,
   whyText,
   handoverText,
@@ -213,20 +214,27 @@ export const HELP = `harbor: Harbor from the terminal
   harbor note PROJECT ["NOTE"] [--opens DATE|--milestone NAME|--off-track]
                                               a note for later: sealed until
                                               its day, milestone, or Off track
-  harbor sound TASK [DAYS] [--why TEXT] [--ask NAMES|crew] [--settle DAYS]
+  harbor sound TASK [--answer DAYS|--ask NAMES|--settle DAYS] [--why TEXT]
                                               a sounding: ask a few people how
                                               many days a task will take, give
                                               your answer, or read the spread
   harbor soundings [PROJECT]                  open tasks with a sounding, and
                                               the ones waiting on your answer
+  harbor ashore [--weeks N] [--country CODES|none] [--person NAME]
+                                              public holidays and time away
+                                              coming up, and whose holidays
+                                              the harbor (or someone) takes
   harbor handover PERSON [--to NAME] [--until DATE] [--note TEXT]
                          [--keep ID,ID] [--confirm]
                                               hand someone's work to the crew
   harbor handback PERSON                      give it back after time away
-  harbor fog [--project P] [--list]           tasks nobody has touched for three
-                                              weeks, one at a time: still
-                                              needed, a new date, or drop it
+  harbor fog [--project P]                    tasks nobody has touched for three
+                                              weeks, longest first
+  harbor fog --sweep [--project P]            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 watch [--project P] [--bell]         a live ticker of the harbor's
+                                              changes; yours bright, q stops
   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
@@ -244,7 +252,7 @@ export const HELP = `harbor: Harbor from the terminal
   DATE: YYYY-MM-DD, today, tomorrow, or +N for N days from today.
   Changes show in Harbor's History as yours, "via Harbor CLI". These commands
   never delete; the full-screen app can, as the website can, and asks first,
-  and so can harbor fog's x (drop it), one task at a time.
+  and so can harbor fog --sweep's x (drop it), one task at a time.
 `;
 
 export const VERSION = JSON.parse(
@@ -446,6 +454,8 @@ const FLAG = {
   days: "the days",
   why: "--why",
   people: "--ask",
+  countries: "--country",
+  country: "--country",
 };
 
 /** Harbor's refusals are worded for agents; say them as the commands and flags that answer them. */
@@ -728,7 +738,8 @@ const DETAIL = {
     "  harbor sound TASK --ask crew           writes: asks you, its owner and whoever",
     "                                         has open work on its project",
     '  harbor sound TASK --ask "Sam,Priya"    writes: asks those people',
-    '  harbor sound TASK 4 [--why "TEXT"]     writes: your answer, in working days',
+    '  harbor sound TASK --answer 4 [--why "TEXT"]',
+    "                                         writes: your answer, in working days",
     "  harbor sound TASK --settle 6           writes: the days you agreed on after",
     "                                         talking a wide spread through",
     "",
@@ -736,6 +747,19 @@ const DETAIL = {
     "  everyone has. Close guesses give the task an estimate; far-apart ones",
     "  say talk first. The forecast draws on every answer.",
   ],
+  ashore: [
+    "  harbor ashore [--weeks N]              reads: holidays and time away in the",
+    "                                         next N weeks (8 unless you say)",
+    "  harbor ashore --country US,GB          writes: whose public holidays the",
+    "                                         harbor takes (none for no holidays)",
+    "  harbor ashore --person NAME --country GB",
+    "                                         writes: one person's own country",
+    "                                         (harbor to take the harbor's again)",
+    "",
+    "  The forecast, the weeks ahead, the timeline and calendar feeds count",
+    "  these as days nobody works. Countries: AU BR CA DE ES FR GB IE IT MX NL",
+    "  NZ US (national holidays only).",
+  ],
   soundings: [
     "  harbor soundings [PROJECT]             reads: open tasks with a sounding",
     "                                         (all projects when left out), and the",
@@ -770,18 +794,29 @@ const DETAIL = {
     '  PERSON is a name, an id, or "me".',
   ],
   fog: [
-    "  harbor fog [--project P]               in a terminal: the tasks in fog, one",
+    "  harbor fog [--project P]               reads them: open tasks nobody has",
+    "                                         opened, moved, edited or commented on",
+    "                                         for three weeks, longest first",
+    "  harbor fog --sweep [--project P]       in a terminal: the tasks in fog, one",
     "                                         at a time. k still needed (clears the",
     "                                         fog), d a new date, x drop it, s skip,",
     "                                         q stop; then it saves what you chose",
-    "  harbor fog --list                      reads them: open tasks nobody has",
-    "                                         opened, moved, edited or commented on",
-    "                                         for three weeks, longest first",
     "  harbor fog keep TASK                   writes: it's still needed, so it",
     "                                         leaves the fog",
     "",
-    "  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.",
+    "  The sweep needs a terminal and full access (harbor login without",
+    "  --read-only), since dropping a task deletes it.",
+  ],
+  watch: [
+    "  harbor watch                           reads, live: each change to the harbor",
+    "                                         as it lands, one line with the time:",
+    "                                         cards moving, comments, health changes",
+    "    --project P     one project's changes only",
+    "    --bell          ring the terminal's bell when something of yours changes",
+    "",
+    "  Lines about your own work (your tasks, mentions of you, what you lead) are",
+    "  bright; the rest are dim. q or Ctrl+C stops. Made for a narrow split or a",
+    "  tmux pane; it needs full access (harbor login without --read-only).",
   ],
   lifeboats: [
     "  harbor lifeboats [--program P]         reads: work only one person has",
@@ -863,7 +898,7 @@ const DETAIL = {
     '  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);",
+    '                                         still stands ("" for no reason);',
     "                                         clears its look again",
     "",
     "  Also --owner me|none|NAME, --impact 1-5, --probability 1-5 (risks),",
@@ -2010,7 +2045,8 @@ export async function run(argv, io = {}) {
       );
       if (!values.project) throw new HarborError("Say which project: --project NAME.");
       // Several at once: one title a line on stdin, with no title (or -) after add.
-      const piped = positionals.length === 0 || (positionals.length === 1 && positionals[0] === "-");
+      const piped =
+        positionals.length === 0 || (positionals.length === 1 && positionals[0] === "-");
       const stdin = io.stdin ?? process.stdin;
       const titles =
         piped && (io.stdin || !process.stdin.isTTY)
@@ -2019,28 +2055,34 @@ export async function run(argv, io = {}) {
               .map((l) => l.trim())
               .filter(Boolean)
           : [text(positionals, "the task")];
-      if (titles.length === 0) throw new HarborError("Say the task, or give one title a line on stdin.");
-      if (titles.length > 100) throw new HarborError("That's more than 100 tasks; harbor import FILE takes a spreadsheet.");
+      if (titles.length === 0)
+        throw new HarborError("Say the task, or give one title a line on stdin.");
+      if (titles.length > 100)
+        throw new HarborError(
+          "That's more than 100 tasks; harbor import FILE takes a spreadsheet.",
+        );
       const added = [];
       for (const title of titles) {
-        const r = await client.call("create_task", {
-          harbor,
-          project: values.project,
-          title,
-          // Yours unless you say otherwise, as with n in the app.
-          assignee: values.assignee ?? "me",
-          due: duePilot(values.due) ? undefined : dueDate(values.due),
-          suggestedDue: duePilot(values.due),
-          priority: values.priority,
-          status: values.status === undefined ? undefined : statusWord(values.status),
-          overLimit: values["over-limit"] || undefined,
-        }).catch((err) => {
-          if (err instanceof HarborError) {
-            const done = added.length ? ` (added ${added.length} before it)` : "";
-            throw new HarborError(`${hint(err.message, values.project)}${done}`);
-          }
-          throw err;
-        });
+        const r = await client
+          .call("create_task", {
+            harbor,
+            project: values.project,
+            title,
+            // Yours unless you say otherwise, as with n in the app.
+            assignee: values.assignee ?? "me",
+            due: duePilot(values.due) ? undefined : dueDate(values.due),
+            suggestedDue: duePilot(values.due),
+            priority: values.priority,
+            status: values.status === undefined ? undefined : statusWord(values.status),
+            overLimit: values["over-limit"] || undefined,
+          })
+          .catch((err) => {
+            if (err instanceof HarborError) {
+              const done = added.length ? ` (added ${added.length} before it)` : "";
+              throw new HarborError(`${hint(err.message, values.project)}${done}`);
+            }
+            throw err;
+          });
         if (values.comment)
           r.comment = (
             await client.call("add_comment", {
@@ -2195,19 +2237,26 @@ export async function run(argv, io = {}) {
       const number = (v, name) => {
         if (v === undefined) return undefined;
         const n = Number(v);
-        if (!Number.isFinite(n) || n <= 0) throw new HarborError(`--${name} is a number of hours, like 2 or 1.5.`);
+        if (!Number.isFinite(n) || n <= 0)
+          throw new HarborError(`--${name} is a number of hours, like 2 or 1.5.`);
         return n;
       };
       const [task, day, ...extra] = positionals;
       if (extra.length) throw new HarborError("Give a task key and a day: harbor week RR-42 wed.");
       const dayHours = number(values["day-hours"], "day-hours");
-      const show = (r) => [r.done, weekText(r, { ...opts, review: Boolean(values.review) })].filter(Boolean).join("\n\n");
+      const show = (r) =>
+        [r.done, weekText(r, { ...opts, review: Boolean(values.review) })]
+          .filter(Boolean)
+          .join("\n\n");
       if (!task && dayHours === undefined) {
-        if (values.off || values.hours) throw new HarborError("Say which task: harbor week RR-42 wed --hours 3.");
+        if (values.off || values.hours)
+          throw new HarborError("Say which task: harbor week RR-42 wed --hours 3.");
         return call("get_week", { harbor, week }, show);
       }
       if (task && !day && !values.off)
-        throw new HarborError(`Say which day for ${task}: harbor week ${task} wed, or --off to take it off the week.`);
+        throw new HarborError(
+          `Say which day for ${task}: harbor week ${task} wed, or --off to take it off the week.`,
+        );
       return call(
         "plan_week",
         {
@@ -2471,9 +2520,14 @@ export async function run(argv, io = {}) {
       );
     }
     case "sound": {
-      const { positionals, values, harbor } = parse(spec([], ["why", "ask", "settle"]));
-      const [task, days, ...extra] = positionals;
+      const { positionals, values, harbor } = parse(spec([], ["answer", "why", "ask", "settle"]));
+      const [task, ...extra] = positionals;
       if (!task) throw new HarborError("Give a task's key, like harbor sound RR-4.");
+      // A bare number used to be the answer; it writes, so it now needs its flag.
+      if (extra.length === 1 && /^\d+(\.\d+)?(d|days?)?$/i.test(extra[0]))
+        throw new HarborError(
+          `To give your answer, say so: harbor sound ${task} --answer ${extra[0]}.`,
+        );
       if (extra.length) throw new HarborError(`Unexpected "${extra.join(" ")}".`);
       const number = (text) => {
         const n = Number(String(text).replace(/d(ays?)?$/i, ""));
@@ -2481,11 +2535,14 @@ export async function run(argv, io = {}) {
           throw new HarborError(`Give days as a number, like 3 or 2.5 (not "${text}").`);
         return n;
       };
+      const days = values.answer;
       const given = [days !== undefined, values.ask !== undefined, values.settle !== undefined];
       if (given.filter(Boolean).length > 1)
         throw new HarborError("Answer, ask or settle: one at a time.");
       if (values.why !== undefined && days === undefined)
-        throw new HarborError('--why goes with your answer: harbor sound TASK 4 --why "TEXT".');
+        throw new HarborError(
+          '--why goes with your answer: harbor sound TASK --answer 4 --why "TEXT".',
+        );
       if (values.ask !== undefined) {
         const crew = /^crew$/i.test(values.ask.trim())
           ? undefined
@@ -2493,11 +2550,10 @@ export async function run(argv, io = {}) {
               .split(",")
               .map((x) => x.trim())
               .filter(Boolean);
-        return call(
-          "take_sounding",
-          { harbor, task, ...(crew ? { people: crew } : {}) },
-          (r) =>
-            `Asked ${r.asked.people.join(", ")} how many days ${r.asked.key ?? r.asked.title} will take. The answers show together once everyone's in.`,
+        return call("take_sounding", { harbor, task, ...(crew ? { people: crew } : {}) }, (r) =>
+          !crew && r.asked.people.length === 1
+            ? `Only you are on this crew, so the sounding on ${r.asked.key ?? r.asked.title} is just your guess. Ask others by name: harbor sound ${task} --ask "Sam,Priya".`
+            : `Asked ${r.asked.people.join(", ")} how many days ${r.asked.key ?? r.asked.title} will take. The answers show together once everyone's in.`,
         );
       }
       if (values.settle !== undefined) {
@@ -2529,6 +2585,39 @@ export async function run(argv, io = {}) {
         soundingsText(r),
       );
     }
+    case "ashore": {
+      const { positionals, values, harbor } = parse(spec([], ["weeks", "country", "person"]));
+      none(positionals);
+      if (values.person && values.country === undefined)
+        throw new HarborError("Give their country too: --person NAME --country GB (or harbor).");
+      if (values.country !== undefined) {
+        if (values.person) {
+          return call(
+            "set_holidays",
+            { harbor, person: values.person, country: values.country },
+            (r) =>
+              r.country === "harbor"
+                ? `${r.person} takes the harbor's holidays.`
+                : `${r.person} takes ${r.country} holidays.`,
+          );
+        }
+        const countries = /^none$/i.test(values.country.trim())
+          ? []
+          : values.country
+              .split(",")
+              .map((c) => c.trim())
+              .filter(Boolean);
+        return call("set_holidays", { harbor, countries }, (r) =>
+          r.harbor.length
+            ? `The harbor takes public holidays from ${r.harbor.map((c) => c.name).join(", ")}.`
+            : "The harbor takes no public holidays now.",
+        );
+      }
+      const weeks = values.weeks === undefined ? 8 : Number(values.weeks);
+      if (!Number.isInteger(weeks) || weeks < 1 || weeks > 52)
+        throw new HarborError("--weeks is a whole number from 1 to 52.");
+      return call("time_ashore", { harbor, days: weeks * 7 }, (r) => ashoreText(r, weeks));
+    }
     case "why": {
       const { positionals, harbor } = parse(spec());
       const of = positionals.join(" ").trim();
@@ -2549,8 +2638,27 @@ export async function run(argv, io = {}) {
       }
       return call("get_voyage_log", { harbor, project }, voyageText, voyageForTerminal);
     }
+    case "watch": {
+      const { positionals, values, harbor } = parse(spec(["bell"], ["project"]));
+      none(positionals);
+      if (!hasFullAccess(creds))
+        throw new HarborError(
+          "Watching needs full access, as the full-screen app does. Run harbor login (without --read-only), then try again.",
+        );
+      const { watchHere } = await loadApp();
+      await watchHere({
+        source: tokenSource({ creds, save: (c) => writeCredentials(c, env), fetcher }),
+        fetcher,
+        harbor,
+        saved: creds.harbor ?? null,
+        project: values.project,
+        bell: Boolean(values.bell),
+        colour: colourDepth(io.stdout ?? process.stdout, env) !== "none",
+      });
+      return 0;
+    }
     case "fog": {
-      const { positionals, values, harbor } = parse(spec(["list"], ["project"]));
+      const { positionals, values, harbor } = parse(spec(["list", "sweep"], ["project"]));
       if (positionals[0] === "keep") {
         const task = one(positionals.slice(1), "task");
         return call(
@@ -2560,8 +2668,17 @@ export async function run(argv, io = {}) {
         );
       }
       none(positionals);
-      const terminal = io.terminal ?? Boolean(process.stdout.isTTY && process.stdin.isTTY);
-      if (terminal && !values.list && !asJson && hasFullAccess(creds)) {
+      // Listing is the default; the sweep, where x deletes, only when asked for.
+      if (values.sweep) {
+        const terminal = io.terminal ?? Boolean(process.stdout.isTTY && process.stdin.isTTY);
+        if (!terminal || asJson) {
+          throw new HarborError("harbor fog --sweep asks about each task, so it needs a terminal.");
+        }
+        if (!hasFullAccess(creds)) {
+          throw new HarborError(
+            "harbor fog --sweep can drop tasks, so it needs full access: harbor login (without --read-only).",
+          );
+        }
         const { fogHere } = await loadApp();
         await fogHere({
           source: tokenSource({ creds, save: (c) => writeCredentials(c, env), fetcher }),

package/lib/format.mjs

@@ -539,7 +539,10 @@ export function voyageText(r) {
 
 /** What's holding something up, as long_pole answers it: the headline, then the line of waits, first blocker at the top. */
 export function whyText(r) {
-  const what = r.of.kind === "task" ? r.of.name : `${r.of.name}${r.of.kind === "milestone" ? " (milestone)" : ""}`;
+  const what =
+    r.of.kind === "task"
+      ? r.of.name
+      : `${r.of.name}${r.of.kind === "milestone" ? " (milestone)" : ""}`;
   if (r.none) return `What's holding up ${what}: ${r.none.replace(/^\w/, (c) => c.toLowerCase())}`;
   const head = [`What's holding up ${what}`];
   if (r.headline) head.push(r.headline);
@@ -552,14 +555,19 @@ export function whyText(r) {
       `  ${(l.key ?? "").padEnd(width)}${width ? "  " : ""}${l.title}`,
       `  ${" ".repeat(width)}${width ? "  " : ""}${l.assignee ?? "nobody yet"} · ${due}${finish} · ${l.slackText}`,
     ];
-    return i < chain.length - 1 ? [...row, `  ${" ".repeat(width ? Math.floor(width / 2) : 0)}│`] : row;
+    return i < chain.length - 1
+      ? [...row, `  ${" ".repeat(width ? Math.floor(width / 2) : 0)}│`]
+      : row;
   });
   const via = r.via ? [`It waits longest on ${r.via.project}; inside it:`] : [];
   const others = (r.others ?? []).length
     ? [
         "",
         `Also waits on ${r.others
-          .map((o) => `${o.project} (finishes ${o.finish}, ${o.slack >= 0 ? `${o.slack} day${o.slack === 1 ? "" : "s"} spare` : `${-o.slack} day${o.slack === -1 ? "" : "s"} over`})`)
+          .map(
+            (o) =>
+              `${o.project} (finishes ${o.finish}, ${o.slack >= 0 ? `${o.slack} day${o.slack === 1 ? "" : "s"} spare` : `${-o.slack} day${o.slack === -1 ? "" : "s"} over`})`,
+          )
           .join(", ")}.`,
       ]
     : [];
@@ -744,7 +752,7 @@ export function soundingText(task, s, { answered = false } = {}) {
     for (const a of s.answers)
       lines.push(`  You said ${daysText(a.days)}${a.why ? ` · "${a.why}"` : ""}`);
     if (s.youWereAsked && !s.answers.length)
-      lines.push(`  Give yours: harbor sound ${task.key ?? task.id} DAYS`);
+      lines.push(`  Give yours: harbor sound ${task.key ?? task.id} --answer DAYS`);
     return lines.join("\n");
   }
   lines.push(`  ${spreadLine(s.answers)}`);
@@ -760,6 +768,26 @@ export function soundingText(task, s, { answered = false } = {}) {
   return lines.join("\n");
 }
 
+/** time_ashore: whose holidays count, then the days off coming up, soonest first. */
+export function ashoreText(r, weeks = 8) {
+  const lines = [];
+  const countries = r.countries ?? [];
+  lines.push(
+    countries.length
+      ? `Time ashore · holidays from ${countries.map((c) => c.name).join(", ")}`
+      : "Time ashore · no holiday country set (harbor ashore --country US)",
+  );
+  for (const p of r.people ?? []) lines.push(`  ${p.name} takes ${p.country} holidays`);
+  const rows = [
+    ...(r.holidays ?? []).map((h) => [h.date, h.name]),
+    ...(r.away ?? []).map((a) => [a.from, `${a.name} away, back ${a.back}`]),
+  ].sort((a, b) => a[0].localeCompare(b[0]));
+  lines.push("");
+  if (!rows.length) lines.push(`  Nothing in the next ${weeks} weeks.`);
+  for (const [day, what] of rows) lines.push(`  ${day}  ${what}`);
+  return lines.join("\n");
+}
+
 /** list_soundings: the ones waiting on you first, then the rest, wide ones flagged. */
 export function soundingsText(r) {
   const all = r.soundings ?? [];
@@ -961,7 +989,7 @@ export function fogText(r, { sweepHint = true } = {}) {
   if (sweepHint)
     lines.push(
       "",
-      "In a terminal, harbor fog walks through them one at a time: k still needed, d new date, x drop it. harbor fog keep TASK keeps one.",
+      "harbor fog --sweep walks through them one at a time: k still needed, d new date, x drop it. harbor fog keep TASK keeps one.",
     );
   return lines.join("\n");
 }
@@ -983,6 +1011,7 @@ export function lifeboatsText(r) {
   });
   if (r.more) lines.push("", `And ${r.count - r.lines.length} more.`);
   for (const a of r.away ?? []) lines.push("", a);
+  if (r.hint) return [...lines, "", r.hint].join("\n");
   lines.push(
     "",
     "harbor lifeboats N adds the suggested second pair of hands (--person NAME for someone else).",

package/package.json

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