@harborppm/cli 0.62.0 → 0.64.0

package/lib/args.mjs

@@ -1,9 +1,10 @@
 /**
  * A small argument reader: positionals, `--flag`, `--key value` and
- * `--key=value`. Unknown flags are an error, so a typo doesn't quietly do
+ * `--key=value`. An option named in `repeat` may be given more than once and
+ * reads as a list. Unknown flags are an error, so a typo doesn't quietly do
  * something else.
  */
-export function parseArgs(argv, { flags = [], options = [] } = {}) {
+export function parseArgs(argv, { flags = [], options = [], repeat = [] } = {}) {
   const positionals = [];
   const values = {};
   for (let i = 0; i < argv.length; i++) {
@@ -20,7 +21,7 @@ export function parseArgs(argv, { flags = [], options = [] } = {}) {
     if (flags.includes(key)) {
       if (inline !== undefined) throw new Error(`--${key} takes no value.`);
       values[key] = true;
-    } else if (options.includes(key)) {
+    } else if (options.includes(key) || repeat.includes(key)) {
       const value = inline ?? argv[++i];
       if (
         value === undefined ||
@@ -29,7 +30,7 @@ export function parseArgs(argv, { flags = [], options = [] } = {}) {
       ) {
         throw new Error(`--${key} needs a value.`);
       }
-      values[key] = value;
+      values[key] = repeat.includes(key) ? [...(values[key] ?? []), value] : value;
     } else {
       throw new Error(`Unknown option --${key}.`);
     }

package/lib/cli.mjs

@@ -103,15 +103,23 @@ export const HELP = `harbor: Harbor from the terminal
   harbor barnacles PROJECT                    work added since the plan was set:
                                               by week, by who, and the days of
                                               slip it explains
+  harbor baseline PROJECT [--reset]           sets a project's baseline: its
+                                              dates now, and growth counted
+                                              from now
   harbor hill [--program P]                   where each project is on its hill
   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
@@ -223,9 +231,10 @@ export const HELP = `harbor: Harbor from the terminal
   harbor voyage PROJECT ["YOUR LINE"]         a Done project's voyage log, and
                                               your line in it
   harbor charter PROJECT [--why T] [--in T] [--out T] [--done-when T]
-                         [--calls T]
-                                              a project's five-line charter:
-                                              read it, or write some lines
+                         [--calls NAME]
+                                              a project's five-line charter
+                                              (why, in, out, done when, who
+                                              makes the calls): read or set
   harbor note PROJECT ["NOTE"] [--opens DATE|--milestone NAME|--off-track]
                                               a note for later: sealed until
                                               its day, milestone, or Off track
@@ -288,9 +297,10 @@ function banner(io, env, words) {
 const THEMES = ["auto", "light", "dark"];
 
 const COMMON = { flags: ["json", "help"], options: ["harbor"] };
-const spec = (flags = [], options = []) => ({
+const spec = (flags = [], options = [], repeat = []) => ({
   flags: [...COMMON.flags, ...flags],
   options: [...COMMON.options, ...options],
+  repeat,
 });
 
 /**
@@ -566,9 +576,14 @@ const DETAIL = {
     "",
     "  --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.",
+    "  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",
@@ -768,14 +783,21 @@ const DETAIL = {
   charter: [
     "  harbor charter PROJECT                 reads its charter, and any open task",
     "                                         that names something it leaves out",
-    '  harbor charter PROJECT --why "TEXT"    writes: that line; give any of',
-    "                                         --why, --in, --out, --done-when and",
-    "                                         --calls at once",
+    "  Set any line, or all at once:",
+    '    --why "TEXT"         why the project exists',
+    '    --in "A, B"          what it covers (the voyage log counts the',
+    "                         finished tasks naming these)",
+    '    --out "C, D"         what it leaves out (tasks naming these show as',
+    "                         Out of scope?)",
+    '    --done-when "TEXT"   what finished looks like',
+    '    --calls "NAME"       who makes the calls when scope is in question',
     "",
-    "  none clears a line: --out none. Separate items in --in and --out",
-    "  with commas, so Harbor can spot a task that names one. The review lists",
-    "  running projects still without a charter a week after they started.",
-    "  PROJECT is a name, a key like RR, or an id.",
+    "  Items in --in and --out are split on commas; give --in or --out again",
+    '  for an item that has a comma in it: --out "Coupons" --out "Gift cards,',
+    '  vouchers". none clears a line: --out none. The review lists running',
+    "  projects still without a charter a week after they started. A charter",
+    "  is for the harbor's members: share links and public roadmaps never show",
+    "  it. PROJECT is a name, a key like RR, or an id.",
   ],
   sound: [
     "  harbor sound TASK                      reads its sounding: who hasn't answered,",
@@ -859,7 +881,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)",
@@ -932,6 +956,30 @@ const DETAIL = {
     "  days before it (negative: that many over). PROJECT is a name, a key",
     "  like RR, or an id.",
   ],
+  clock: [
+    "  harbor clock                           reads everyone's local time, and",
+    "                                         who's working now",
+    "  harbor clock NAME                      reads one person's",
+    "  harbor clock [NAME] --zone ZONE        writes: sets a time zone (yours",
+    "                                         without NAME)",
+    "  harbor clock [NAME] --hours 9-17       writes: sets working hours",
+    "",
+    "  ZONE is an IANA name like America/New_York or Europe/London, here for",
+    "  this machine's zone, or none to clear the zone and hours. --hours is",
+    "  one start and end in that zone, like 9-17, 8:30-16:30 or 9am-5:30pm,",
+    "  Monday to Friday: one span a day that ends after it starts, so no split",
+    "  day or overnight shift. Without --hours a day runs 9 to 17. Agents",
+    "  don't keep hours.",
+  ],
+  baseline: [
+    "  harbor baseline PROJECT                writes: commits its start and end",
+    "                                         dates as its baseline",
+    "  harbor baseline PROJECT --reset        writes: replaces one already set",
+    "",
+    "  The timeline then shows slips against those dates, and harbor barnacles",
+    "  counts tasks added from now on as growth. On the website a program's",
+    "  Set baseline does the same for all its projects.",
+  ],
   barnacles: [
     "  harbor barnacles PROJECT               reads how much the plan has grown",
     "",
@@ -1291,6 +1339,7 @@ export async function run(argv, io = {}) {
       const now = await readCredentials(env);
       return now ? { ...c, harbor: now.harbor ?? null, harborName: now.harborName ?? null } : c;
     };
+    const settings = await readSettings(env);
     await runApp({
       source: tokenSource({
         creds,
@@ -1304,9 +1353,20 @@ export async function run(argv, io = {}) {
         const now = (await readCredentials(env)) ?? creds;
         await writeCredentials({ ...now, harbor: h.id, harborName: h.name }, env);
       },
-      theme: (await readSettings(env)).theme,
+      theme: settings.theme,
       browse: io.browse ?? openBrowser,
       ...(command === "bridge" ? { startIn: "bridge" } : {}),
+      // When this machine last saw you in each harbor: the app opens on a
+      // catch-up after a few days away (src/lib/welcome-back.ts).
+      seen: {
+        last: (id) => settings.seen?.[id] ?? null,
+        mark: (id, at) => {
+          settings.seen = { ...settings.seen, [id]: at };
+          void readSettings(env)
+            .then((now) => writeSettings({ ...now, seen: { ...now.seen, [id]: at } }, env))
+            .catch(() => {});
+        },
+      },
     });
     return 0;
   }
@@ -1900,6 +1960,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}`));
@@ -2160,11 +2222,38 @@ export async function run(argv, io = {}) {
         );
       if (values["dry-run"]) {
         const n = titles.length === 1 ? "1 task" : `${titles.length} tasks`;
-        if (asJson) out(jsonText({ dryRun: true, project: values.project, titles }));
+        // --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) => `  ${t}`)].join("\n"),
+              [
+                `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;
@@ -2393,6 +2482,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(
@@ -2594,11 +2728,15 @@ export async function run(argv, io = {}) {
     }
     case "charter": {
       const { positionals, values, harbor } = parse(
-        spec([], ["why", "in", "out", "done-when", "calls"]),
+        spec([], ["why", "done-when", "calls"], ["in", "out"]),
       );
       const project = one(positionals, 'project: harbor charter "NAME"');
-      // none clears a line, as --due none does.
-      const line = (v) => (v.trim().toLowerCase() === "none" ? "" : v);
+      // none clears a line, as --due none does. --in and --out given more than
+      // once write one item each, as a bulleted list, so an item keeps its commas.
+      const line = (v) => {
+        if (Array.isArray(v)) v = v.length > 1 ? v.map((x) => `- ${x.trim()}`).join("\n") : v[0];
+        return v.trim().toLowerCase() === "none" ? "" : v;
+      };
       const lines = Object.fromEntries(
         [
           ["why", values.why],
@@ -2741,6 +2879,19 @@ export async function run(argv, io = {}) {
       if (!project) throw new HarborError("Say which project: harbor barnacles PROJECT.");
       return call("scope_growth", { harbor, project }, barnaclesText);
     }
+    case "baseline": {
+      const { positionals, values, harbor } = parse(spec(["reset"]));
+      const project = positionals.join(" ").trim();
+      if (!project) throw new HarborError("Say which project: harbor baseline PROJECT.");
+      return call(
+        "set_baseline",
+        { harbor, project, ...(values.reset ? { reset: true } : {}) },
+        (r) =>
+          r.changed
+            ? `Set ${r.project}'s baseline: ${r.baselineStart} to ${r.baselineEnd}. harbor barnacles counts tasks added from now on.`
+            : `${r.project} already has a baseline (${r.baselineStart} to ${r.baselineEnd}); --reset replaces it.`,
+      );
+    }
     case "voyage": {
       const { positionals, harbor } = parse(spec());
       const [project, ...words] = positionals;

package/lib/format.mjs

@@ -635,6 +635,7 @@ export function barnaclesText(r) {
   }
   head.push(`${r.headline} (${r.planned} planned, ${r.addedThisWeek} added this week).`);
   if (r.daysLine) head.push(r.daysLine);
+  if (r.caveat) head.push(r.caveat);
   const top = Math.max(1, ...r.byWeek.map((w) => w.added));
   const weeks = r.byWeek.map(
     (w) => `  w/c ${w.weekOf}  ${"█".repeat(Math.max(1, Math.round((w.added / top) * 20)))} ${w.added}`,
@@ -643,7 +644,7 @@ export function barnaclesText(r) {
   const from =
     r.measuredFrom === "when the baseline was set"
       ? `Counted from when the baseline was set, ${r.since.slice(0, 10)}.`
-      : `Counted from a week after its first task was made, ${r.since.slice(0, 10)}; setting a baseline counts from then instead.`;
+      : `Counted from a week after its first task was made, ${r.since.slice(0, 10)}; harbor baseline "${r.project}" counts from then instead.`;
   return [...head, "", "Added by week:", ...weeks, "", `By who: ${who}`, "", from].join("\n");
 }
 
@@ -751,12 +752,16 @@ const CHARTER_LINES = [
 export function charterText(r) {
   const project = r.name ?? r.project;
   if (!r.charter) {
-    return `${project} has no charter yet. Write one, a line at a time:\n  harbor charter "${project}" --why "…" --in "…, …" --out "…, …" --done-when "…" --calls "…"`;
+    return `${project} has no charter yet. Set any line, or all at once:\n  harbor charter "${project}" --why "…" --in "…, …" --out "…, …" --done-when "…" --calls "…"`;
   }
   const lines = [`Charter · ${project}`];
   const width = Math.max(...CHARTER_LINES.map(([, label]) => label.length));
   for (const [key, label] of CHARTER_LINES) {
-    if (r.charter[key]) lines.push(`  ${label.padEnd(width)}  ${r.charter[key]}`);
+    // A bulleted In or Out (--in given more than once) keeps its lines lined up.
+    if (r.charter[key])
+      lines.push(
+        `  ${label.padEnd(width)}  ${String(r.charter[key]).replace(/\n/g, `\n  ${" ".repeat(width)}  `)}`,
+      );
   }
   if (r.outOfScope?.length) {
     lines.push("", "Out of scope?");

package/package.json

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