@harborppm/cli 0.44.0 → 0.46.0

package/lib/cli.mjs

@@ -78,6 +78,13 @@ export const HELP = `harbor: Harbor from the terminal
                                               projects with health and open work
                                               (--json adds each board's limits)
   harbor forecast [PROJECT] [--program P]     when projects will likely finish
+  harbor try PROJECT [--drop KEYS] [--add "TITLE" [--count N]]
+                     [--due KEY=DATE] [--give KEY=NAME] [--end DATE]
+                     [--borrow NAME[=DAYS]] [--release NAME]
+                     [--saved] [--apply|--save|--discard]
+                                              dry dock: the forecast with plan
+                                              changes tried on a copy; nothing
+                                              changes without --apply
   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
@@ -115,7 +122,9 @@ export const HELP = `harbor: Harbor from the terminal
   harbor add "TITLE" --project P [--assignee me|none|NAME] [--due DATE]
                      [--priority low|medium|high|urgent] [--status S]
                      [--over-limit]
-  harbor start TASK | review TASK | done TASK [--confirm] [--over-limit]
+  harbor start TASK | submit TASK | done TASK [--confirm] [--over-limit]
+                                              move a task to In play, In review
+                                              or Done
   harbor edit TASK [--title T] [--assignee me|none|NAME] [--due DATE|none]
                    [--priority P] [--status S] [--notes TEXT]
                    [--repeat weekly|biweekly|monthly|never]
@@ -139,9 +148,10 @@ export const HELP = `harbor: Harbor from the terminal
                      [--notes T]
                                               one risk, issue or decision in
                                               full, or change it
-  harbor review [--mine|--owner NAME] [--portfolio P] [--done]
+  harbor review [WORDS] [--mine|--owner NAME] [--portfolio P] [--done]
                                               the review: programs worst first,
-                                              each with its next move
+                                              each with its next move (reads
+                                              only; harbor submit moves a task)
   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
@@ -534,6 +544,33 @@ const DETAIL = {
     "  than the pace would finish sets the dates, and the forecast names it. It",
     "  warns when under two weeks of pace is all there is.",
   ],
+  try: [
+    "  harbor try PROJECT [changes]           reads the forecast with the changes",
+    "                                         tried on a copy of the plan",
+    "  harbor try PROJECT [changes] --apply   writes: makes the changes for real",
+    "  harbor try PROJECT [changes] --save    writes: keeps them on the project to",
+    "                                         show someone (Forecast tab, Open dry",
+    "                                         dock)",
+    "  harbor try PROJECT --saved             reads the saved ones (add changes,",
+    "                                         --apply or --save as above)",
+    "  harbor try PROJECT --discard           writes: throws the saved ones away",
+    "",
+    "  Changes, each taking several with commas between:",
+    "    --drop RL-4,RL-5        take tasks out of the plan (--apply removes them)",
+    '    --add "TITLE" --count N new work, N tasks called TITLE',
+    "    --due RL-4=fri          move a due date (none takes it off)",
+    "    --give RL-4=Sam         give a task to someone (none: nobody)",
+    "    --end 2026-12-19        move the project's end date",
+    "    --borrow Sam=3          someone joins 3 days a week (5 if left out);",
+    "                            --apply raises their share of the program",
+    "    --release Priya         someone leaves: their open tasks lose their owner",
+    "",
+    "  It prints the real plan and the changed one side by side: when it's",
+    "  probably and very likely done, open tasks, the chance of making the end",
+    "  date, the crew's pace, and the load of everyone the changes touch. A",
+    "  borrowed person adds an average crew member's pace for each day a week",
+    "  they give; a released one takes away their share of what was finished.",
+  ],
   report: [
     "  harbor report PROGRAM                  reads the program's status report",
     "",
@@ -658,8 +695,10 @@ const DETAIL = {
     "                                         project in or hold a task in",
     "  harbor review --owner NAME             the same for someone else",
     "  harbor review --portfolio P            one portfolio's",
-    "  harbor review TASK                     writes: moves a task to In review",
+    '  harbor review "WORDS"                  only programs whose name has them',
     "",
+    "  The review only reads. To move a task to In review, run harbor submit",
+    "  TASK (harbor review TASK did that before 0.45.0, and now says so).",
     '  Write a next move with harbor next-move PROGRAM "TEXT"; set a health by',
     "  hand with harbor health. harbor export review prints it as CSV.",
   ],
@@ -789,6 +828,13 @@ async function harborNamed(client, key) {
 
 const TASK_KEY = /^[A-Za-z][A-Za-z0-9]{0,9}-\d+$/;
 
+/** True when every word of `words` is somewhere in `name`, any case. */
+const nameHas = (name, words) =>
+  words
+    .toLowerCase()
+    .split(/\s+/)
+    .every((w) => name.toLowerCase().includes(w));
+
 /**
  * A task by its key, else a project by name, else a task by id: its web
  * link and what to call it. Harbor's own refusal when nothing matches.
@@ -919,6 +965,7 @@ export async function run(argv, io = {}) {
         await writeCredentials({ ...now, harbor: h.id, harborName: h.name }, env);
       },
       theme: (await readSettings(env)).theme,
+      browse: io.browse ?? openBrowser,
     });
     return 0;
   }
@@ -1069,6 +1116,100 @@ export async function run(argv, io = {}) {
     return 0;
   }
 
+  if (command === "try") {
+    const { values, positionals } = parseArgs(rest, {
+      flags: ["apply", "save", "discard", "saved", "json"],
+      options: ["harbor", "drop", "add", "count", "due", "give", "end", "borrow", "release"],
+    });
+    if (positionals.length !== 1)
+      throw new HarborError(
+        positionals.length
+          ? "harbor try takes one project; put a name with spaces in quotes."
+          : "Say which project: harbor try PROJECT --drop RL-4. harbor help try has the rest.",
+      );
+    if (["apply", "save", "discard"].filter((k) => values[k]).length > 1)
+      throw new HarborError("Use one of --apply, --save or --discard.");
+    const creds = await readCredentials(env);
+    if (!hasFullAccess(creds))
+      throw new HarborError(
+        creds
+          ? "This sign-in can only read. Run harbor login (without --read-only) to use dry dock."
+          : "Not signed in. Run harbor login, or harbor signup if you're new.",
+      );
+    const app = await loadApp();
+    const notes = [];
+    const say = values.json ? (line) => notes.push(line) : (line) => out(plain(line));
+    const result = await app.tryHere({
+      transport: app.planTransport(
+        tokenSource({ creds, save: (c) => writeCredentials(c, env), fetcher }),
+        fetcher,
+      ),
+      project: positionals[0],
+      flags: values,
+      apply: Boolean(values.apply),
+      save: Boolean(values.save),
+      discard: Boolean(values.discard),
+      say,
+      pickHarbor: (list) => {
+        if (values.harbor) return app.harborNamed(list, values.harbor);
+        const saved = list.find((h) => h.id === creds?.harbor);
+        if (saved) return saved;
+        if (list.length === 1) return list[0];
+        throw new HarborError(
+          `You're in ${list.length} harbors (${list.map((h) => h.name).join(", ")}). Add --harbor NAME, or run harbor use NAME first.`,
+        );
+      },
+    });
+    if (!result) {
+      if (values.json) out(jsonText({ notes }));
+      return 0;
+    }
+    if (values.json) {
+      const side = (s) => ({
+        endDate: s.project.endDate,
+        open: s.open,
+        likely: s.tide.kind === "forecast" ? s.tide.likely : null,
+        veryLikely: s.tide.kind === "forecast" ? s.tide.veryLikely : null,
+        chanceByEnd: s.tide.kind === "forecast" ? s.tide.chanceByEnd : null,
+        forecast: s.tide.kind,
+      });
+      const c = result.comparison;
+      out(
+        jsonText({
+          project: { id: result.project.id, key: result.project.key, name: result.project.name },
+          changes: result.changes,
+          real: side(c.real),
+          dryDock: side(c.docked),
+          shiftDays: c.shift,
+          pace: c.pace,
+          ...(result.applied !== undefined ? { applied: result.applied } : {}),
+          ...(result.saved ? { saved: true } : {}),
+          notes,
+        }),
+      );
+      return 0;
+    }
+    for (const line of result.lines) out(plain(line));
+    out("");
+    if (result.applied !== undefined)
+      out(
+        plain(
+          `⚓ Applied ${result.applied} change${result.applied === 1 ? "" : "s"} to ${result.project.name}.`,
+        ),
+      );
+    else if (result.saved)
+      out(
+        plain(
+          `⚓ Saved on ${result.project.name}. It's on the Forecast tab under Open dry dock; --apply makes it real.`,
+        ),
+      );
+    else if (result.changes.length)
+      out(
+        "Nothing was changed. Add --apply to make these changes, or --save to keep them to show someone.",
+      );
+    return 0;
+  }
+
   if (command === "init" || command === "sync") {
     const init = command === "init";
     const { values, positionals } = parseArgs(rest, {
@@ -1581,6 +1722,7 @@ export async function run(argv, io = {}) {
       );
     }
     case "start":
+    case "submit":
     case "review":
     case "done": {
       const { positionals, values, harbor } = parse(
@@ -1588,7 +1730,17 @@ export async function run(argv, io = {}) {
           ? spec(["confirm", "over-limit", "mine", "done"], ["owner", "portfolio"])
           : spec(["confirm", "over-limit"]),
       );
-      if (command === "review" && positionals.length === 0) {
+      if (command === "review") {
+        // The review only reads: a task key here once moved the task, so it says where that went.
+        const words = positionals.join(" ").trim();
+        if (TASK_KEY.test(words)) {
+          throw new HarborError(
+            `harbor review only reads the review now. To move ${words} to In review, run harbor submit ${words}.`,
+          );
+        }
+        if (values.confirm || values["over-limit"]) {
+          throw new HarborError("--confirm and --over-limit are for moving a task: harbor submit TASK.");
+        }
         if (values.mine && values.owner) throw new HarborError("Say --mine or --owner, not both.");
         return call(
           "program_review",
@@ -1598,15 +1750,14 @@ export async function run(argv, io = {}) {
             portfolio: values.portfolio,
             includeDone: Boolean(values.done),
           },
-          reviewList,
-        );
-      }
-      if (values.mine || values.done || values.owner || values.portfolio) {
-        throw new HarborError(
-          "--mine, --owner, --portfolio and --done are for the review: harbor review on its own.",
+          (r) =>
+            words && r.programs.length === 0
+              ? `No program in the review matches "${words}".`
+              : reviewList(r),
+          (r) => (words ? { ...r, programs: r.programs.filter((p) => nameHas(p.name, words)) } : r),
         );
       }
-      const status = { start: "doing", review: "review", done: "done" }[command];
+      const status = { start: "doing", submit: "review", done: "done" }[command];
       return call(
         "update_task",
         {
@@ -2005,7 +2156,8 @@ export async function run(argv, io = {}) {
         ([k, v]) => !["harbor", "item"].includes(k) && v !== undefined,
       );
       if (!changes.length) {
-        return call("get_raid", { harbor, item }, (r) => raidDetail(r.item));
+        // --json gives the item itself, as harbor show does a task.
+        return call("get_raid", { harbor, item }, raidDetail, (r) => r.item ?? r);
       }
       return call("update_raid", args, (r) => `Updated.\n\n${raidDetail(r.updated)}`);
     }

package/package.json

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