@harborppm/cli 0.70.0 → 0.71.0

package/lib/cli.mjs

@@ -156,7 +156,7 @@ export const HELP = `harbor: Harbor from the terminal
                        [--ends DATE] [--budget N] [--from "DONE PROJECT"]
                                               --from: plan it from a finished
                                               project as that one really ran
-  harbor add "TITLE" --project P [--assignee me|none|NAME]
+  harbor add "TITLE" [--project P] [--assignee me|none|NAME]
                      [--due DATE|pilot] [--priority low|medium|high|urgent]
                      [--status S] [--comment TEXT] [--over-limit] [--dry-run]
                                               with no TITLE: one title a line
@@ -284,6 +284,10 @@ export const HELP = `harbor: Harbor from the terminal
   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 --sweep's x (drop it), one task at a time.
+  Practice: a new harbor starts with First voyage, a project of practice
+  tasks that tick themselves off as you try things; the brief, harbor week,
+  bridge and forecast leave it out. To look around a made-up harbor instead,
+  open harborppm.com/demo or run ssh try.harborppm.com.
 `;
 
 /**
@@ -442,6 +446,32 @@ const REPEAT_WORD = { weekly: "every week", biweekly: "every two weeks", monthly
 
 const WEEKDAYS = ["sunday", "monday", "tuesday", "wednesday", "thursday", "friday", "saturday"];
 
+/** The one open project a task can go in (First voyage aside), or why --project is needed. */
+async function onlyProject(client, harbor) {
+  const r = await client.call("list_projects", {
+    harbor,
+    health: ["on-track", "at-risk", "off-track", "paused"],
+    limit: 5,
+  });
+  const open = (r.projects ?? []).filter((p) => p.id !== "voyage");
+  if (open.length === 1) return open[0].name;
+  if (open.length === 0)
+    throw new HarborError('This harbor has no open project yet; harbor project "NAME" --program P makes one.');
+  const names = open.slice(0, 3).map((p) => p.name);
+  const more = open.length > 3 || r.total > 5 ? ", …" : "";
+  throw new HarborError(`Say which project: --project NAME (${names.join(", ")}${more}).`);
+}
+
+const WEEKDAY_NAME = WEEKDAYS.map((d) => d[0].toUpperCase() + d.slice(1));
+
+/** The Monday of a day's week; Saturday and Sunday look ahead to the next, as Harbor's weeks do. */
+function mondayOf(iso) {
+  const d = new Date(`${iso}T12:00:00`);
+  const wd = d.getDay();
+  const back = wd === 0 ? -1 : wd === 6 ? -2 : wd - 1;
+  return todayLocal(new Date(d.getFullYear(), d.getMonth(), d.getDate() - back));
+}
+
 /** "fri", "Friday": how many days until that weekday comes round (today counts). */
 function daysToWeekday(v, today) {
   const w = v.toLowerCase();
@@ -621,6 +651,9 @@ const DETAIL = {
     "  harbor add --project P --dry-run       reads: says what it would add, and",
     "                                         adds nothing",
     "",
+    "  --project can be left out when the harbor has one open project (First",
+    "  voyage aside); the task goes there.",
+    "",
     "  --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",
@@ -645,7 +678,10 @@ const DETAIL = {
     "  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.",
+    "  day yet, since they wait on someone else. A weekday already gone this",
+    "  week means next week's (mon on a Friday is the coming Monday); add",
+    "  --week today to plan this week's. First voyage's practice tasks are left",
+    "  out.",
   ],
   init: [
     "  harbor init [PROJECT] [--hook]         writes: .harbor/ at the top of this",
@@ -1809,7 +1845,7 @@ export async function run(argv, io = {}) {
   const client = createClient({ creds, save: (c) => writeCredentials(c, env), fetcher });
   // A terminal's lines fit its width; piped output stays whole for scripts.
   const opts = {
-    today: todayLocal(),
+    today: todayLocal(io.now ? new Date(io.now()) : new Date()),
     width: process.stdout.isTTY ? process.stdout.columns : undefined,
   };
 
@@ -2298,7 +2334,8 @@ export async function run(argv, io = {}) {
           ["project", "assignee", "due", "priority", "status", "comment"],
         ),
       );
-      if (!values.project) throw new HarborError("Say which project: --project NAME.");
+      // No --project: the harbor's one open project, if that's all there is.
+      if (!values.project) values.project = await onlyProject(client, harbor);
       // 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] === "-");
@@ -2335,7 +2372,11 @@ export async function run(argv, io = {}) {
               dryRun: true,
               project: values.project,
               titles,
-              ...(pilot ? { due: pilot.map((d) => d.earliest) } : {}),
+              ...(pilot
+                ? { due: pilot.map((d) => d.earliest) }
+                : values.due
+                  ? { due: titles.map(() => dueDate(values.due)) }
+                  : {}),
             }),
           );
         else
@@ -2343,7 +2384,10 @@ export async function run(argv, io = {}) {
             plain(
               [
                 `Would add ${n} to ${values.project}:`,
-                ...titles.map((t, i) => `  ${t}${pilot ? `  (due ${pilot[i].earliest})` : ""}`),
+                ...titles.map(
+                  (t, i) =>
+                    `  ${t}${pilot ? `  (due ${pilot[i].earliest})` : values.due ? `  (due ${dueDate(values.due)})` : ""}`,
+                ),
                 ...(pilot
                   ? [
                       `--due pilot: ${pilot[0].says}; ${pilot[0].why.map((w) => w.charAt(0).toLowerCase() + w.slice(1)).join("; ")}.`,
@@ -2536,11 +2580,14 @@ export async function run(argv, io = {}) {
           throw new HarborError(`--${name} is a number of hours, like 2 or 1.5.`);
         return n;
       };
-      // The day comes as --day; a bare second word still works, as it did first.
+      // The day comes as --day; a bare second word (the first form) is refused, not guessed.
       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;
+      if (bareDay && !extra.length && !values.day)
+        throw new HarborError(
+          `Say the day with --day: harbor week ${task} --day ${bareDay.toLowerCase()}.`,
+        );
+      if (bareDay) throw new HarborError("Give a task key and a day: harbor week RR-42 --day wed.");
+      const day = values.day;
       const dayHours = number(values["day-hours"], "day-hours");
       const show = (r) =>
         [r.done, weekText(r, { ...opts, review: Boolean(values.review) })]
@@ -2555,18 +2602,28 @@ export async function run(argv, io = {}) {
         throw new HarborError(
           `Say which day for ${task}: harbor week ${task} --day wed, or --off to take it off the week.`,
         );
+      // A weekday already gone this week means the next one, as --due friday does.
+      let planWeek = week;
+      let ahead = "";
+      if (day && !values.off && !values.week && !values.next && !values.last) {
+        const next = dueDate(day, new Date(`${opts.today}T12:00:00`));
+        if (next !== day && mondayOf(next) !== mondayOf(opts.today)) {
+          planWeek = next;
+          ahead = `${WEEKDAY_NAME[new Date(`${next}T12:00:00`).getDay()]} has gone this week, so that's next week's (${next}); add --week today for this week's.`;
+        }
+      }
       return call(
         "plan_week",
         {
           harbor,
-          week,
+          week: planWeek,
           ...(task ? { task } : {}),
           ...(day ? { day } : {}),
           ...(values.hours ? { hours: number(values.hours, "hours") } : {}),
           ...(values.off ? { remove: true } : {}),
           ...(dayHours !== undefined ? { dayHours } : {}),
         },
-        show,
+        (r) => [ahead, show(r)].filter(Boolean).join("\n\n"),
       );
     }
     case "comment": {

package/lib/format.mjs

@@ -31,10 +31,13 @@ export function statusWord(typed) {
  * piped output keeps every title whole.
  */
 export function taskLine(t, { today, mine = false, width } = {}) {
-  const late = t.due && today && t.due < today && t.status !== "done";
+  const open = t.status !== "done";
+  const late = t.due && today && t.due < today && open;
+  // Today and tomorrow in words, so what's close stands out from the dates.
+  const soon = open && today && t.due ? soonWord(t.due, today) : null;
   const bits = [
     STATUS[t.status] ?? t.status,
-    t.due ? (late ? `late, due ${t.due}` : `due ${t.due}`) : null,
+    t.due ? (late ? `late, due ${t.due}` : soon ? `due ${soon}` : `due ${t.due}`) : null,
     t.priority && t.priority !== "medium" ? t.priority : null,
     mine ? null : (t.assignee ?? null),
     t.project ?? null,
@@ -45,6 +48,14 @@ export function taskLine(t, { today, mine = false, width } = {}) {
   return key + fitTitle(t.title, width ? width - 1 - key.length - tail.length : Infinity) + tail;
 }
 
+/** "today" or "tomorrow" for a due date that close, else null. */
+function soonWord(due, today) {
+  if (due === today) return "today";
+  const d = new Date(`${today}T12:00:00`);
+  d.setDate(d.getDate() + 1);
+  return due === todayLocal(d) ? "tomorrow" : null;
+}
+
 /** The title cut to `room` characters with an ellipsis, but never below 20. */
 function fitTitle(title, room) {
   const chars = [...title];
@@ -1053,7 +1064,10 @@ export function weekText(w, { today, review = false, width } = {}) {
       }
     }
     if (w.unplannedCount) {
-      out.push("", `Not on a day yet: ${w.unplannedCount}. harbor week KEY DAY puts one there.`);
+      out.push(
+        "",
+        `Not on a day yet: ${w.unplannedCount}. harbor week KEY --day 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)

package/package.json

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