@harborppm/cli 0.60.0 → 0.62.0

package/lib/cli.mjs

@@ -39,9 +39,11 @@ import {
   lifeboatsText,
   followedText,
   soundingsText,
+  thanksText,
   ashoreText,
   voyageText,
   whyText,
+  bridgeText,
   barnaclesText,
   handoverText,
   fogText,
@@ -143,10 +145,11 @@ export const HELP = `harbor: Harbor from the terminal
                                               project as that one really ran
   harbor add "TITLE" --project P [--assignee me|none|NAME]
                      [--due DATE|pilot] [--priority low|medium|high|urgent]
-                     [--status S] [--comment TEXT] [--over-limit]
+                     [--status S] [--comment TEXT] [--over-limit] [--dry-run]
                                               with no TITLE: one title a line
                                               from stdin; --due pilot takes the
                                               date the owner's queue suggests
+                                              (harbor help add)
   harbor start TASK | submit TASK | done TASK [--confirm] [--over-limit]
                                               move a task to In play, In review
                                               or Done
@@ -161,9 +164,10 @@ export const HELP = `harbor: Harbor from the terminal
                                               your own week: tasks on days
                                               against your hours, only for
                                               you; --review: planned vs done
-  harbor week TASK DAY [--hours N]            put a task on a day: mon to fri
-  harbor week TASK --off [DAY]                take it off that day, or the week
+  harbor week TASK --day DAY [--hours N]      put a task on a day: mon to fri
+  harbor week TASK --off [--day DAY]          take it off that day, or the week
   harbor week --day-hours N                   the hours you work a day
+                                              (harbor help week)
   harbor comment TASK "TEXT"
   harbor checkin "WHAT YOU'RE DOING" [--on-blocker]
   harbor risk "TITLE" --project P|--program P [--impact 1-5] [--probability 1-5]
@@ -188,10 +192,17 @@ export const HELP = `harbor: Harbor from the terminal
                                               the review: programs worst first,
                                               each with its next move (reads
                                               only; harbor submit moves a task)
+  harbor thanks [--all] [--given]             thanks you were given this month
+  harbor thanks TASK "LINE" [--to NAME]       a one-line thanks for a task
+  harbor thanks --milestone NAME|--decision TITLE "LINE" [--to NAME]
+                                              the same for a milestone or a
+                                              decision
   harbor bridge [--harbor H]                  run the review as a meeting: one
                                               project a screen, what changed
                                               since the last one, decisions,
                                               actions and risks logged live
+  harbor bridge --list [--program P]          what changed since the last
+                                              review, as text (or --json)
   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
@@ -239,6 +250,8 @@ export const HELP = `harbor: Harbor from the terminal
   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 watch --once [--since TIME] [--json] the latest changes (or all since
+                                              TIME), printed once, for scripts
   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
@@ -544,6 +557,34 @@ export function voyageForTerminal(r, project = r.project) {
 
 /** Commands whose forms do different things: one line each, saying which read and which write. */
 const DETAIL = {
+  add: [
+    '  harbor add "TITLE" --project P         writes: one task, yours unless',
+    "                                         --assignee says otherwise",
+    "  harbor add --project P < titles.txt    writes: one task a line of stdin",
+    "  harbor add --project P --dry-run       reads: says what it would add, and",
+    "                                         adds nothing",
+    "",
+    "  --assignee me|none|NAME, --due DATE|pilot, --priority low|medium|high|urgent,",
+    "  --status S, --comment TEXT and --over-limit apply to every task added, so",
+    "  ten lines with --comment add the same comment to all ten. --due pilot",
+    "  takes the date the owner's queue suggests. More than 100 lines is harbor",
+    "  import's job.",
+  ],
+  week: [
+    "  harbor week [--next|--last|--week DATE] reads: your week, the days and",
+    "                                         their hours, and what's not on a",
+    "                                         day yet",
+    "  harbor week --review                   reads: what you planned against",
+    "                                         what you finished",
+    "  harbor week TASK --day DAY [--hours N] writes: puts the task on that day",
+    "                                         (mon to fri), 2 hours unless --hours",
+    "  harbor week TASK --off [--day DAY]     writes: takes it off that day, or",
+    "                                         off the week",
+    "  harbor week --day-hours N              writes: the hours you work a day",
+    "",
+    "  Only you see your week. Tasks in review are left out of what's not on a",
+    "  day yet, since they wait on someone else.",
+  ],
   init: [
     "  harbor init [PROJECT] [--hook]         writes: .harbor/ at the top of this",
     "                                         repository, one file per task in",
@@ -817,10 +858,18 @@ const DETAIL = {
     "                                         cards moving, comments, health changes",
     "    --project P     one project's changes only",
     "    --bell          ring the terminal's bell when something of yours changes",
+    "    --since TIME    start with every change since TIME (14:30 today, or",
+    "                    2026-10-21, or 2026-10-21T14:30) instead of the last 5",
+    "    --once          print those and stop instead of listening",
+    "    --json          one JSON object a line (at, text, quote, mine, tone;",
+    "                    earlier: true for the ones from before it started)",
     "",
-    "  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).",
+    "  It starts with the latest few changes and a \"since HH:MM\" line, then",
+    "  prints each new one as it lands. Lines about your own work (your tasks,",
+    "  mentions of you, what you lead) are bright; the rest are dim. It runs",
+    "  until q or Ctrl+C (or until it's killed, when piped or with --json);",
+    "  --once returns at once. 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",
@@ -927,19 +976,40 @@ const DETAIL = {
     "  enough of it to pick one out; harbor risks lists them. Changes several",
     "  at once, as one change.",
   ],
+  thanks: [
+    "  harbor thanks                          reads the thanks you were given in",
+    "                                         the last 30 days, newest first",
+    "  harbor thanks --all                    everyone's; --given: the ones you gave",
+    '  harbor thanks RR-42 "LINE"             writes: thanks whoever has the task',
+    '  harbor thanks --milestone NAME "LINE"  writes: thanks for a milestone (its',
+    "                                         sign-off person unless --to says)",
+    '  harbor thanks --decision TITLE "LINE"  writes: thanks whoever made the call',
+    "  --to NAME                              someone else instead",
+    "",
+    "  Fair winds: a thanks shows on the work, on the person's card on People,",
+    "  in the next brief and in the project's voyage log. Nobody can thank",
+    "  themselves, and nothing counts or ranks them.",
+  ],
   bridge: [
     "  harbor bridge                          opens the full-screen app on the",
     "                                         review meeting (b on the Programs",
     "                                         screen, or : Run the review meeting)",
+    "  harbor bridge --list [--program P]     prints the agenda instead: what",
+    "                                         changed on each project since its",
+    "                                         program's last review, every item",
+    "                                         (--json for scripts and agents; the",
+    "                                         same when piped). Reading it doesn't",
+    "                                         count as holding the meeting",
     "",
     "  One open project a screen, with only what changed since its program was",
     "  last reviewed (a week back the first time): health moves, work finished,",
     "  newly late or added, risks raised, decisions made. ←→ move between",
     "  projects; d logs a decision, a an action (who takes it, due in a week),",
-    "  r a risk, m the program's next move; e ends it. The summary lists what",
-    "  was logged; p posts it to each program's chat channel where one is set",
-    "  (Ship to shore, set on the website), y copies it. The next meeting",
-    "  counts from when this one ended.",
+    "  r a risk, m the program's next move, v shows every item behind an",
+    "  \"and N more\" (↑↓ scroll); e ends it, Esc or q leaves without ending",
+    "  it. The summary lists what was logged; p posts it to each program's",
+    "  chat channel where one is set (Ship to shore, set on the website), y",
+    "  copies it. The next meeting counts from when this one ended.",
   ],
   review: [
     "  harbor review                          reads the review: every program,",
@@ -1164,8 +1234,14 @@ export async function run(argv, io = {}) {
   }
 
   // On its own in a terminal: the full-screen app. Piped or scripted: the help.
-  if (!command || command === "app" || command === "bridge") {
-    const terminal = io.terminal ?? Boolean(process.stdout.isTTY && process.stdin.isTTY);
+  const inTerminal = io.terminal ?? Boolean(process.stdout.isTTY && process.stdin.isTTY);
+  // harbor bridge --list (or --json, or piped) prints the agenda through the commands below.
+  const bridgeApp =
+    command === "bridge" &&
+    inTerminal &&
+    !rest.some((a) => a === "--list" || a === "--json" || a.startsWith("--program"));
+  if (!command || command === "app" || bridgeApp) {
+    const terminal = inTerminal;
     if (!command && !terminal) {
       out(HELP);
       return 0;
@@ -2059,7 +2135,10 @@ export async function run(argv, io = {}) {
     }
     case "add": {
       const { positionals, values, harbor } = parse(
-        spec(["over-limit"], ["project", "assignee", "due", "priority", "status", "comment"]),
+        spec(
+          ["over-limit", "dry-run"],
+          ["project", "assignee", "due", "priority", "status", "comment"],
+        ),
       );
       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.
@@ -2079,6 +2158,17 @@ export async function run(argv, io = {}) {
         throw new HarborError(
           "That's more than 100 tasks; harbor import FILE takes a spreadsheet.",
         );
+      if (values["dry-run"]) {
+        const n = titles.length === 1 ? "1 task" : `${titles.length} tasks`;
+        if (asJson) out(jsonText({ dryRun: true, project: values.project, titles }));
+        else
+          out(
+            plain(
+              [`Would add ${n} to ${values.project}:`, ...titles.map((t) => `  ${t}`)].join("\n"),
+            ),
+          );
+        return 0;
+      }
       const added = [];
       for (const title of titles) {
         const r = await client
@@ -2244,7 +2334,7 @@ export async function run(argv, io = {}) {
     }
     case "week": {
       const { positionals, values, harbor } = parse(
-        spec(["next", "last", "review", "off"], ["week", "hours", "day-hours"]),
+        spec(["next", "last", "review", "off"], ["week", "hours", "day-hours", "day"]),
       );
       if ([values.next, values.last, values.week].filter(Boolean).length > 1)
         throw new HarborError("Say one of --next, --last or --week DATE.");
@@ -2259,21 +2349,24 @@ export async function run(argv, io = {}) {
           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.");
+      // The day comes as --day; a bare second word still works, as it did first.
+      const [task, bareDay, ...extra] = positionals;
+      if (extra.length || (bareDay && values.day))
+        throw new HarborError("Give a task key and a day: harbor week RR-42 --day wed.");
+      const day = values.day ?? bareDay;
       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");
       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 || values.day)
+          throw new HarborError("Say which task: harbor week RR-42 --day 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.`,
+          `Say which day for ${task}: harbor week ${task} --day wed, or --off to take it off the week.`,
         );
       return call(
         "plan_week",
@@ -2663,13 +2756,18 @@ 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"]));
+      const { positionals, values, harbor } = parse(spec(["bell", "once"], ["project", "since"]));
       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();
+      const { watchHere, watchSince } = await loadApp();
+      const since = values.since ? watchSince(values.since, new Date()) : null;
+      if (values.since && !since)
+        throw new HarborError(
+          `--since takes a time today (14:30) or a date (2026-10-21, or 2026-10-21T14:30), not "${values.since}".`,
+        );
       await watchHere({
         source: tokenSource({ creds, save: (c) => writeCredentials(c, env), fetcher }),
         fetcher,
@@ -2677,7 +2775,10 @@ export async function run(argv, io = {}) {
         saved: creds.harbor ?? null,
         project: values.project,
         bell: Boolean(values.bell),
-        colour: colourDepth(io.stdout ?? process.stdout, env) !== "none",
+        colour: !asJson && colourDepth(io.stdout ?? process.stdout, env) !== "none",
+        since,
+        once: Boolean(values.once),
+        json: asJson,
       });
       return 0;
     }
@@ -2716,6 +2817,49 @@ export async function run(argv, io = {}) {
       }
       return call("fog", { harbor, project: values.project, limit: 100 }, (r) => fogText(r));
     }
+    case "bridge": {
+      const { positionals, values, harbor } = parse(spec(["list"], ["program"]));
+      none(positionals);
+      return call("review_meeting", { harbor, program: values.program }, bridgeText);
+    }
+    case "thanks": {
+      const { positionals, values, harbor } = parse(
+        spec(["all", "given"], ["to", "milestone", "decision"]),
+      );
+      const forWork = values.milestone || values.decision;
+      if (!forWork && positionals.length === 0) {
+        return call(
+          "list_thanks",
+          {
+            harbor,
+            person: values.all ? "all" : "me",
+            given: Boolean(values.given),
+          },
+          thanksText,
+        );
+      }
+      const [first, ...rest] = positionals;
+      const task = forWork ? undefined : first;
+      const line = (forWork ? positionals : rest).join(" ").trim();
+      if (task && !TASK_KEY.test(task) && !line) {
+        throw new HarborError(
+          'Say what for and the line: harbor thanks RR-42 "Caught it before launch" (or --milestone NAME, --decision TITLE).',
+        );
+      }
+      if (!line) throw new HarborError('Add the line of thanks in quotes: harbor thanks RR-42 "Thank you".');
+      return call(
+        "give_thanks",
+        {
+          harbor,
+          task,
+          milestone: values.milestone,
+          decision: values.decision,
+          to: values.to,
+          line,
+        },
+        (r) => `Fair winds: thanked ${r.thanked.to ?? "them"} for ${r.thanked.for}.`,
+      );
+    }
     case "handover": {
       const { positionals, values, harbor } = parse(
         spec(["confirm"], ["to", "until", "note", "keep"]),

package/lib/format.mjs

@@ -526,15 +526,66 @@ export function premortemText(r, project = r.project) {
 }
 
 /** A project's voyage log, as get_voyage_log answers it. */
+/** `harbor thanks`: each thanks on two lines, the words first, no counts. */
+export function thanksText(r) {
+  if (r.note) return r.note;
+  if (!r.thanks.length) {
+    return r.person
+      ? `No thanks in the last ${r.days} days yet. harbor thanks TASK "LINE" gives one.`
+      : `Nobody has thanked anyone in the last ${r.days} days. harbor thanks TASK "LINE" gives one.`;
+  }
+  return r.thanks
+    .map((t) => `“${t.line}”\n  ${t.from} to ${t.to}, for ${t.for} · ${t.at.slice(0, 10)}`)
+    .join("\n");
+}
+
 export function voyageText(r) {
   const head = [`Voyage log · ${r.project}${r.done ? ` · Done ${r.finished}` : " · not Done yet"}`];
   if (r.note) head.push(r.note);
   head.push((r.stats ?? []).join(" · "));
   const story = (r.story ?? []).map((s) => `  - ${s}`);
   const crew = (r.crew ?? []).map((c) => `  - ${c.who ?? "Someone"}: ${c.line}`);
-  return [...head, "", ...story, ...(crew.length ? ["", "From the crew:", ...crew] : [])].join(
-    "\n",
+  const thanks = (r.thanks ?? []).map(
+    (t) => `  - ${t.from ?? "Someone"} to ${t.to ?? "someone"}: “${t.line}”`,
   );
+  return [
+    ...head,
+    "",
+    ...story,
+    ...(thanks.length ? ["", "Fair winds along the way:", ...thanks] : []),
+    ...(crew.length ? ["", "From the crew:", ...crew] : []),
+  ].join("\n");
+}
+
+/** The review meeting's agenda, as review_meeting answers it: each project that moved, with every item. */
+export function bridgeText(r) {
+  const programs = r.programs ?? [];
+  if (programs.length === 0) return "No open programs to review.";
+  const out = programs.map(
+    (p) =>
+      `${p.name}: changes since ${p.lastReviewed ? "the last review" : "last week"}, ${p.since.slice(0, 10)}`,
+  );
+  for (const p of r.projects ?? []) {
+    const facts = [
+      p.health,
+      p.lead,
+      p.ends ? `ends ${p.ends}` : null,
+      `${p.late} late of ${p.open} open`,
+      p.highRisks ? `${p.highRisks} high risk${p.highRisks === 1 ? "" : "s"}` : null,
+      p.nextMilestone ? `next milestone ${p.nextMilestone.name}, ${p.nextMilestone.due}` : null,
+    ].filter(Boolean);
+    out.push("", `${p.project} (${p.program})`, `  ${facts.join(" · ")}`);
+    for (const c of p.changes) {
+      if (c.items) {
+        out.push(`  - ${c.text.split(":")[0]} (${c.items.length}):`);
+        for (const item of c.items) out.push(`      ${item}`);
+      } else out.push(`  - ${c.text}`);
+    }
+  }
+  if ((r.projects ?? []).length === 0) out.push("", "Nothing moved since the last review.");
+  const quiet = (r.quiet ?? []).map((q) => q.project);
+  if (quiet.length) out.push("", `No change on ${quiet.join(", ")}.`);
+  return out.join("\n");
 }
 
 /** What's holding something up, as long_pole answers it: the headline, then the line of waits, first blocker at the top. */
@@ -978,8 +1029,16 @@ export function weekText(w, { today, review = false, width } = {}) {
       out.push("", `Not on a day yet: ${w.unplannedCount}. harbor week KEY DAY puts one there.`);
       for (const t of w.unplanned.slice(0, 5))
         out.push(`  ${taskLine(t, { today, mine: true, width: width ? width - 2 : undefined })}`);
-      if (w.unplannedCount > 5) out.push(`  … and ${w.unplannedCount - 5} more (--json lists 25)`);
+      if (w.unplannedCount > 5)
+        out.push(
+          `  … and ${w.unplannedCount - 5} more (--json lists ${w.unplannedCount > w.unplanned.length ? w.unplanned.length : "all"})`,
+        );
     }
+    if (w.inReviewCount)
+      out.push(
+        "",
+        `${w.inReviewCount} of yours ${w.inReviewCount === 1 ? "is" : "are"} in review, waiting on someone else, so ${w.inReviewCount === 1 ? "it's" : "they're"} left out.`,
+      );
   }
   if (reviewing) {
     const r = w.review;

package/package.json

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