@harborppm/cli 0.61.0 → 0.63.0

package/lib/cli.mjs

@@ -107,11 +107,16 @@ export const HELP = `harbor: Harbor from the terminal
   harbor hill PROJECT --at 0-100|top|done     move it: up to 50 is figuring it
                                               out, past 50 is getting it done
   harbor mine                                 what's on you, late first
+  harbor clock [NAME] [--zone ZONE|here|none] [--hours 9-17]
+                                              who's working now, or set your
+                                              (or NAME's) time zone and hours
   harbor tasks [words] [--project P] [--assignee me|none|NAME]
                      [--late] [--status S,S] [--all]
                                               the first 20 (--all: every one);
                                               done ones only with --status done
-  harbor show TASK                            one task (TASK: a key like RR-42)
+  harbor show TASK                            one task (TASK: a key like RR-42),
+                                              with the date its owner's queue
+                                              suggests
   harbor open [TASK|PROJECT]                  open it on the website (or Today)
   harbor invite EMAIL [--viewer]              invite someone to your harbor
   harbor prompt [--shell SHELL] [--refresh]   due today and late, for your
@@ -145,10 +150,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
@@ -163,9 +169,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]
@@ -555,6 +562,39 @@ 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. More than 100",
+    "  lines is harbor import's job.",
+    "",
+    "  --due pilot takes the earliest day the owner's queue suggests: their open",
+    "  work due first, their weekly pace, time away, what it waits on and how",
+    "  long their similar tasks took. It needs an owner (--assignee none is",
+    "  refused), and an empty queue gives their next working day. Several lines",
+    "  each count the ones before them; with --dry-run it shows each line's date.",
+  ],
+  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",
@@ -829,7 +869,9 @@ const DETAIL = {
     "    --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",
+    "                    2026-10-21, or 2026-10-21T14:30) instead of the last 5;",
+    "                    times are this computer's, or UTC with Z or UTC after",
+    "                    (14:30Z), and the header names the zone",
     "    --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)",
@@ -1870,6 +1912,8 @@ export async function run(argv, io = {}) {
           ),
         ];
         if (t.repeats) lines.push(`Repeats ${REPEAT_WORD[t.repeats] ?? t.repeats}.`);
+        if (t.pilotDue?.fits) lines.push(`${t.pilotDue.says}, so the due date holds.`);
+        else if (t.pilotDue) lines.push(...pilotLines({ pilot: t.pilotDue }, t));
         if (t.description) lines.push("", t.description);
         if (t.checklist.length)
           lines.push("", ...t.checklist.map((c) => `  [${c.done ? "x" : " "}] ${c.step}`));
@@ -2105,7 +2149,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.
@@ -2125,6 +2172,44 @@ 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`;
+        // --due pilot: the date each line would take, each counting the ones before it.
+        const pilot = duePilot(values.due)
+          ? (
+              await client.call("suggest_due", {
+                harbor,
+                project: values.project,
+                assignee: values.assignee ?? "me",
+                count: titles.length,
+              })
+            ).dates
+          : null;
+        if (asJson)
+          out(
+            jsonText({
+              dryRun: true,
+              project: values.project,
+              titles,
+              ...(pilot ? { due: pilot.map((d) => d.earliest) } : {}),
+            }),
+          );
+        else
+          out(
+            plain(
+              [
+                `Would add ${n} to ${values.project}:`,
+                ...titles.map((t, i) => `  ${t}${pilot ? `  (due ${pilot[i].earliest})` : ""}`),
+                ...(pilot
+                  ? [
+                      `--due pilot: ${pilot[0].says}; ${pilot[0].why.map((w) => w.charAt(0).toLowerCase() + w.slice(1)).join("; ")}.`,
+                    ]
+                  : []),
+              ].join("\n"),
+            ),
+          );
+        return 0;
+      }
       const added = [];
       for (const title of titles) {
         const r = await client
@@ -2290,7 +2375,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.");
@@ -2305,21 +2390,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",
@@ -2346,6 +2434,51 @@ export async function run(argv, io = {}) {
           `Comment added to ${r.commented.task}${r.mentioned?.length ? `; told ${r.mentioned.join(", ")}` : ""}.`,
       );
     }
+    case "clock": {
+      const { positionals, values, harbor } = parse(spec([], ["zone", "hours"]));
+      const who = positionals.join(" ").trim();
+      if (values.zone === undefined && values.hours === undefined) {
+        return call("crew_clocks", { harbor }, (r) => {
+          const rows = who ? r.clocks.filter((c) => nameHas(c.who, who)) : r.clocks;
+          const quiet = who ? r.noTimeZone.filter((n) => nameHas(n, who)) : r.noTimeZone;
+          if (rows.length === 0 && quiet.length === 0) {
+            return who ? `Nobody on the crew matches "${who}".` : "Nobody on the crew yet.";
+          }
+          const width = Math.max(0, ...rows.map((c) => c.who.length));
+          return [
+            ...rows.map(
+              (c) =>
+                `${c.who.padEnd(width)}  ${c.localTime.padStart(5)}  ${c.zone.replace(/_/g, " ")}  ${c.working ? `working (${c.hours})` : (c.picksUp ?? "off")}`,
+            ),
+            ...(quiet.length
+              ? [
+                  `${rows.length ? "\n" : ""}No time zone yet: ${quiet.join(", ")}. harbor clock --zone here sets yours.`,
+                ]
+              : []),
+          ].join("\n");
+        });
+      }
+      let zone = values.zone;
+      if (zone?.toLowerCase() === "here") {
+        zone = Intl.DateTimeFormat().resolvedOptions().timeZone;
+        if (!zone) throw new HarborError("This machine doesn't say its time zone. Give one, like --zone Europe/London.");
+      }
+      let starts;
+      let ends;
+      if (values.hours !== undefined) {
+        const m = /^\s*([^-–]+?)\s*[-–]\s*(.+?)\s*$/.exec(values.hours);
+        if (!m) throw new HarborError("--hours is a start and an end, like 9-17 or 8:30-16:30.");
+        [, starts, ends] = m;
+      }
+      return call(
+        "set_clock",
+        { harbor, person: who || "me", zone, starts, ends },
+        (r) =>
+          r.zone
+            ? `${r.person}: ${r.zone.replace(/_/g, " ")}, ${r.hours} on weekdays. ${r.working ? `Working now (${r.localTime} there).` : (r.picksUp ?? "")}`.trim()
+            : `${r.person} has no time zone now.`,
+      );
+    }
     case "checkin": {
       const { positionals, values, harbor } = parse(spec(["on-blocker"]));
       return call(

package/lib/format.mjs

@@ -1029,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.61.0",
+  "version": "0.63.0",
   "description": "Harbor from the terminal: a full-screen app with everything, plus commands for scripts and agents.",
   "keywords": [
     "harbor",