@harborppm/cli 0.5.0 → 0.6.0

package/README.md

@@ -51,22 +51,27 @@ It runs on the same engine as the website: health, task keys, limits and undo wo
 
 ```
 harbor harbors                              the harbors you belong to
+harbor use HARBOR|none                      the harbor commands mean when you're in several
 harbor mine                                 what's on you, late first
-harbor tasks [words] [--project P] [--assignee me|NAME] [--late] [--status S]
+harbor tasks [words] [--project P] [--assignee me|none|NAME] [--late] [--status S,S]
 harbor show TASK                            one task in full
 
 harbor add "TITLE" --project P [--assignee me|NAME] [--due YYYY-MM-DD]
-                   [--priority low|medium|high|urgent] [--status S]
-harbor start TASK | review TASK | done TASK [--confirm]
+                   [--priority low|medium|high|urgent] [--status S] [--over-limit]
+harbor start TASK | review TASK | done TASK [--confirm] [--over-limit]
 harbor edit TASK [--title T] [--assignee me|none|NAME] [--due DATE|none]
-                 [--priority P] [--status S]
+                 [--priority P] [--status S] [--confirm] [--over-limit]
 harbor comment TASK "TEXT"
 harbor checkin "WHAT YOU'RE DOING" [--on-blocker]
-harbor risk "TITLE" [--project P] [--impact 1-5] [--probability 1-5]
-harbor issue "TITLE" [--project P]
+harbor risk "TITLE" --project P|--program P [--impact 1-5] [--probability 1-5]
+                   [--owner NAME] [--due YYYY-MM-DD]
+harbor issue "TITLE" --project P|--program P [--impact 1-5] [--owner NAME]
+                    [--due YYYY-MM-DD]
 ```
 
-Every command takes `--harbor NAME` when you're in more than one, and `--json` for the raw result. Statuses are backlog, todo, doing, review and done.
+Every command takes `--json` for the raw result, and `harbor COMMAND --help` shows just that command. Statuses are backlog, todo, doing, review and done.
+
+When you belong to more than one harbor, say which: `--harbor NAME` on the command, or `harbor use NAME` once (it's saved with your sign-in; `harbor use none` forgets it). With neither, the commands ask rather than guess, so nothing lands in the wrong harbor. The full-screen app opens the one `harbor use` set too.
 
 Harbor holds back what it would hold back in the app: finishing a task that still waits on another, or going past a column's limit. The CLI says so and names the flag that goes ahead (`--confirm`, `--over-limit`).
 

package/bin/harbor.mjs

@@ -22,6 +22,7 @@ run(argv).then(
   async (err) => {
     const known =
       err instanceof HarborError ||
+      err?.name === "HarborError" ||
       /^(Unknown option|--\S+ (needs|takes|is))/.test(err?.message ?? "");
     // Harbor's refusals can quote a task's title; print them plain.
     process.stderr.write(

package/dist/app.mjs

@@ -1707,9 +1707,17 @@ function numberNewTasks(before, after) {
 		projects
 	};
 	const was = byId(before.tasks);
+	const holders = /* @__PURE__ */ new Map();
+	for (const t of after.tasks) {
+		if (!Number.isInteger(t.number)) continue;
+		const k = `${t.projectId}:${t.number}`;
+		holders.set(k, (holders.get(k) ?? 0) + 1);
+	}
+	const keepsNumber = (t) => Number.isInteger(t.number) && holders.get(`${t.projectId}:${t.number}`) === 1;
 	const fresh = (t) => {
 		const old = was.get(t.id);
-		return !old || old.projectId !== t.projectId && old.number === t.number;
+		if (!old) return !keepsNumber(t);
+		return old.projectId !== t.projectId && old.number === t.number;
 	};
 	if (!after.tasks.some(fresh)) return projects === after.projects ? after : {
 		...after,
@@ -1855,12 +1863,17 @@ function openBlockerNames(task, tasks) {
 function waitingOn(task, tasks) {
 	return tasks.filter((t) => t.id !== task.id && waitsOn(t, task.id) && t.status !== "done");
 }
+const escapeRegExp = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+/**
+* Who a comment mentions: "@" and a first name as a whole word, so @Samantha
+* isn't Sam and an address (jane@nico.com) mentions nobody.
+*/
 function parseMentions(body, people) {
 	const ids = /* @__PURE__ */ new Set();
-	const lower = body.toLowerCase();
 	for (const person of people) {
-		const needle = `@${person.name.split(" ")[0].toLowerCase()}`;
-		if (lower.includes(needle)) ids.add(person.id);
+		const first = person.name.trim().split(/\s+/)[0];
+		if (!first) continue;
+		if (new RegExp(`(?<![\\p{L}\\p{N}_])@${escapeRegExp(first)}(?![\\p{L}\\p{N}_-])`, "iu").test(body)) ids.add(person.id);
 	}
 	return [...ids];
 }
@@ -2078,8 +2091,9 @@ function forecastLine(f) {
 //#endregion
 //#region src/tui/theme.ts
 /**
-* Dark: Harbor's teal and coral lifted so they read on black, with the plain
-* colours every terminal draws for status. Light: the brand's own darker teal
+* Dark: Harbor's teal and coral lifted so they read on black, and status in
+* softened hues rather than the terminal's own loud green and yellow (a
+* 16-colour terminal still gets its nearest plain colour). Light: the brand's own darker teal
 * and coral, and status in hues dark enough for text on white (4.5:1 or more).
 */
 const PALETTES = {
@@ -2089,10 +2103,10 @@ const PALETTES = {
 		muted: "gray",
 		selected: "#3dbcab",
 		border: "gray",
-		good: "green",
-		warn: "yellow",
-		bad: "red",
-		done: "cyan"
+		good: "#86c294",
+		warn: "#e3b55c",
+		bad: "#f2665d",
+		done: "#7fb6cc"
 	},
 	light: {
 		accent: "#0f6e64",
@@ -2906,7 +2920,10 @@ function HistoryView({ active, width, height, go }) {
 						}),
 						/* @__PURE__ */ jsx(Text, {
 							bold: true,
-							children: actorOf(row, people)
+							children: actorOf({
+								...row,
+								via: null
+							}, people)
 						}),
 						row.via ? /* @__PURE__ */ jsxs(Text, {
 							color: theme.muted,
@@ -2993,7 +3010,7 @@ function listNames(names) {
 	return `${names.slice(0, -1).join(", ")} and ${names[names.length - 1]}`;
 }
 function excerpt(body) {
-	const t = body.replace(/@\w+/g, "").replace(/\s+/g, " ").trim();
+	const t = body.replace(/(?<![\p{L}\p{N}_])@[\p{L}\p{N}_-]+/gu, "").replace(/\s+/g, " ").trim();
 	if (t.length <= 96) return t;
 	return `${t.slice(0, 94)}…`;
 }
@@ -3462,17 +3479,19 @@ function PeopleView({ active, width, height, go }) {
 	const { today } = useDeps();
 	const rows = useMemo(() => {
 		const now = /* @__PURE__ */ new Date(`${today()}T12:00:00`);
+		const nameWidth = Math.max(0, ...people.map((p) => p.name.length));
 		return people.map((p) => {
 			const open = tasks.filter((t) => t.assigneeId === p.id && t.status !== "done");
 			const load = weeklyLoad(tasks, p.id, now, 4);
 			const cap = p.weeklyCapacity ?? 5;
-			const weeks = load.weeks.map((w) => w.due > cap ? `${w.due}!` : String(w.due)).join(" ");
+			const weeks = load.weeks.map((w) => (w.due === 0 ? "·" : w.due > cap ? `${w.due}!` : String(w.due)).padStart(3)).join("");
+			const late = load.overdue ? `${load.overdue} late` : "";
 			return {
 				id: p.id,
 				kind: "person",
 				depth: 0,
-				title: p.name,
-				detail: `${p.role} · ${open.length} open${load.overdue ? ` · ${load.overdue} late` : ""} · next 4 weeks ${weeks} of ${cap}`
+				title: p.name.padEnd(nameWidth),
+				detail: `${String(open.length).padStart(3)} open  ${late.padEnd(7)}  weeks${weeks}  of ${cap}  · ${p.role}`
 			};
 		});
 	}, [
@@ -5166,7 +5185,7 @@ function ProjectView({ projectId, active, width, height, go, onBack }) {
 		]
 	});
 }
-/** One card on the board: its key, owner and due date, then the title on up to two lines. */
+/** One card on the board: its key, due date and owner, then the title on up to two lines. */
 function Card({ taskKey, title, owner, due, late, waits, priority, selected }) {
 	return /* @__PURE__ */ jsxs(Box, {
 		flexDirection: "column",
@@ -5182,10 +5201,6 @@ function Card({ taskKey, title, owner, due, late, waits, priority, selected }) {
 				}),
 				" ",
 				/* @__PURE__ */ jsx(PriorityMark, { priority }),
-				owner ? /* @__PURE__ */ jsxs(Text, {
-					color: selected ? void 0 : theme.muted,
-					children: [" ", owner]
-				}) : null,
 				due ? /* @__PURE__ */ jsxs(Text, {
 					color: late ? theme.bad : selected ? void 0 : theme.muted,
 					children: [" ", due]
@@ -5193,6 +5208,10 @@ function Card({ taskKey, title, owner, due, late, waits, priority, selected }) {
 				waits ? /* @__PURE__ */ jsx(Text, {
 					color: theme.warn,
 					children: " waits"
+				}) : null,
+				owner ? /* @__PURE__ */ jsxs(Text, {
+					color: selected ? void 0 : theme.muted,
+					children: [" ", owner]
 				}) : null
 			]
 		}), /* @__PURE__ */ jsx(Box, {
@@ -5464,7 +5483,7 @@ function TaskPanel({ taskId, width, height, go, onClose }) {
 		status: STATUS_LABEL[task.status],
 		assignee: owner?.name ?? "Nobody yet",
 		due: task.dueDate ? `${shortDay(task.dueDate, day)}${isLate(task, day) ? " (late)" : ""}` : "None",
-		priority: task.priority,
+		priority: PRIORITY_LABEL[task.priority],
 		project: project ? `${project.name}${project.key ? ` (${project.key})` : ""}` : "",
 		notes: task.description.replace(/\s+/g, " ").trim() || "None"
 	};
@@ -5525,7 +5544,7 @@ function TaskPanel({ taskId, width, height, go, onClose }) {
 		} else if (f === "priority") editor = /* @__PURE__ */ jsx(Picker, {
 			title: "Priority",
 			choices: PRIORITIES.map((p) => ({
-				label: p,
+				label: PRIORITY_LABEL[p],
 				value: p
 			})),
 			initial: PRIORITIES.indexOf(task.priority),
@@ -5628,7 +5647,7 @@ function TaskPanel({ taskId, width, height, go, onClose }) {
 				children: [
 					"  ",
 					"Checklist",
-					task.checklist.length ? ` ${task.checklist.filter((c) => c.done).length}/${task.checklist.length}` : ""
+					task.checklist.length ? ` ${task.checklist.filter((c) => c.done).length}/${task.checklist.length}` : " · none yet, a adds a step"
 				]
 			}),
 			task.checklist.map((item, i) => {
@@ -8943,6 +8962,17 @@ function createSync(opts) {
 	};
 }
 
+//#endregion
+//#region cli/lib/errors.mjs
+/**
+* What the CLI says when something stops a command: a HarborError is
+* already worded for the person and printed as it is; anything else is
+* unexpected and printed as "Something went wrong".
+*/
+var HarborError = class extends Error {
+	name = "HarborError";
+};
+
 //#endregion
 //#region src/tui/theme-detect.ts
 const isThemeSetting = (v) => v === "auto" || v === "light" || v === "dark";
@@ -9060,20 +9090,36 @@ async function startApp(deps, options = {}) {
 		ui
 	};
 }
+/**
+* The harbor --harbor names, as the commands read it: its id, its whole
+* name, or the one name it best matches.
+*/
+function harborNamed(harbors, key) {
+	const want = key.trim();
+	const exact = harbors.find((h) => h.id === want) ?? harbors.find((h) => h.name.trim().toLowerCase() === want.toLowerCase());
+	if (exact) return exact;
+	const hits = harbors.map((h) => ({
+		h,
+		s: scoreMatch(want, h.name)
+	})).filter((x) => x.s > 0).sort((a, b) => b.s - a.s);
+	if (hits.length === 0) throw new HarborError(`No harbor matches "${want}". Run harbor harbors.`);
+	if (hits.length > 1 && hits[0].s === hits[1].s) {
+		const names = hits.map((x) => x.h.name).join(", ");
+		throw new HarborError(`"${want}" matches more than one harbor: ${names}.`);
+	}
+	return hits[0].h;
+}
 /** `harbor`: sign-in already done, take over the terminal until q. */
 async function runApp(opts) {
 	const theme = await pickTheme(opts.theme);
 	const transport = httpTransport(opts.source, opts.fetcher);
 	const { account, harbors } = await transport.harbors();
-	if (harbors.length === 0) throw new Error("You don't belong to a harbor yet. Make one at harborppm.com first.");
-	const wanted = opts.harbor?.toLowerCase();
-	const pick = wanted ? harbors.find((h) => h.id === opts.harbor || h.name.toLowerCase() === wanted) : void 0;
-	if (wanted && !pick) throw new Error(`No harbor called "${opts.harbor}".`);
+	if (harbors.length === 0) throw new HarborError(`You don't belong to a harbor yet. Make one at ${opts.source.server} first.`);
 	const { instance } = await startApp({
 		transport,
 		account,
 		harbors,
-		workspaceId: pick?.id,
+		workspaceId: (opts.harbor ? harborNamed(harbors, opts.harbor) : void 0)?.id,
 		splashMs: SPLASH_MS,
 		theme
 	}, { alternateScreen: true });
@@ -9081,4 +9127,4 @@ async function runApp(opts) {
 }
 
 //#endregion
-export { SPLASH_MS, TransportError, httpTransport, runApp, startApp };
+export { SPLASH_MS, TransportError, harborNamed, httpTransport, runApp, startApp };

package/lib/args.mjs

@@ -22,7 +22,11 @@ export function parseArgs(argv, { flags = [], options = [] } = {}) {
       values[key] = true;
     } else if (options.includes(key)) {
       const value = inline ?? argv[++i];
-      if (value === undefined || (inline === undefined && value.startsWith("--"))) {
+      if (
+        value === undefined ||
+        value.trim() === "" ||
+        (inline === undefined && value.startsWith("--"))
+      ) {
         throw new Error(`--${key} needs a value.`);
       }
       values[key] = value;

package/lib/auth.mjs

@@ -5,6 +5,7 @@
  */
 import { createHash, randomBytes } from "node:crypto";
 import { createServer } from "node:http";
+import { HarborError, reach } from "./errors.mjs";
 
 export const CLIENT_NAME = "Harbor CLI";
 export const WRITE_SCOPE = "harbor:write";
@@ -36,7 +37,7 @@ async function json(res, what) {
 
 /** The server's OAuth endpoints, from its discovery document. */
 export async function discover(server, fetcher = fetch) {
-  const res = await fetcher(new URL("/.well-known/oauth-authorization-server", server));
+  const res = await reach(fetcher, new URL("/.well-known/oauth-authorization-server", server));
   return json(res, "Finding Harbor's sign-in");
 }
 
@@ -98,7 +99,7 @@ export async function login({ server, readOnly = false, open, fetcher = fetch, n
   const { redirectUri, code } = await listenForCode(state);
 
   const client = await json(
-    await fetcher(meta.registration_endpoint, {
+    await reach(fetcher, meta.registration_endpoint, {
       method: "POST",
       headers: { "content-type": "application/json" },
       body: JSON.stringify({
@@ -120,14 +121,12 @@ export async function login({ server, readOnly = false, open, fetcher = fetch, n
     state,
     code_challenge: challenge,
     code_challenge_method: "S256",
-    scope: readOnly
-      ? "openid offline_access"
-      : `openid offline_access ${WRITE_SCOPE} ${APP_SCOPE}`,
+    scope: readOnly ? "openid offline_access" : `openid offline_access ${WRITE_SCOPE} ${APP_SCOPE}`,
   }).toString();
   await open(authorize.toString());
 
   const tokens = await json(
-    await fetcher(meta.token_endpoint, {
+    await reach(fetcher, meta.token_endpoint, {
       method: "POST",
       headers: { "content-type": "application/x-www-form-urlencoded" },
       body: new URLSearchParams({
@@ -157,18 +156,21 @@ export function toCredentials(server, tokenEndpoint, clientId, tokens, at) {
 
 /** New tokens from the refresh token; the old one stops working. */
 export async function refresh(creds, { fetcher = fetch, now = Date.now } = {}) {
-  if (!creds.refreshToken) throw new Error("Signed out. Run harbor login.");
-  const tokens = await json(
-    await fetcher(creds.tokenEndpoint, {
-      method: "POST",
-      headers: { "content-type": "application/x-www-form-urlencoded" },
-      body: new URLSearchParams({
-        grant_type: "refresh_token",
-        refresh_token: creds.refreshToken,
-        client_id: creds.clientId,
-      }),
+  if (!creds.refreshToken) throw new HarborError("Signed out. Run harbor login.");
+  const res = await reach(fetcher, creds.tokenEndpoint, {
+    method: "POST",
+    headers: { "content-type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({
+      grant_type: "refresh_token",
+      refresh_token: creds.refreshToken,
+      client_id: creds.clientId,
     }),
-    "Refreshing your sign-in",
-  );
+  });
+  // Refused: the sign-in was disconnected in Harbor, or renewed by another
+  // copy of these credentials (a refresh token is good once).
+  if (res.status === 400 || res.status === 401) {
+    throw new HarborError("Your sign-in on this machine has ended. Run harbor login.");
+  }
+  const tokens = await json(res, "Refreshing your sign-in");
   return toCredentials(creds.server, creds.tokenEndpoint, creds.clientId, tokens, now());
 }

package/lib/cli.mjs

@@ -27,24 +27,28 @@ export const HELP = `harbor: Harbor from the terminal
   harbor login [--server URL] [--read-only]   sign in (opens your browser once)
   harbor logout                               forget the sign-in on this machine
   harbor harbors                              the harbors you belong to
+  harbor use HARBOR|none                      the harbor commands mean when you're in several
   harbor theme [auto|light|dark]              the app's colours (auto asks the terminal)
   harbor --version                            which version this is
 
   harbor mine                                 what's on you, late first
-  harbor tasks [words] [--project P] [--assignee me|NAME] [--late] [--status S]
+  harbor tasks [words] [--project P] [--assignee me|none|NAME] [--late] [--status S,S]
   harbor show TASK                            one task in full (TASK: its key, RR-42, or id)
 
   harbor add "TITLE" --project P [--assignee me|NAME] [--due YYYY-MM-DD]
-                     [--priority low|medium|high|urgent] [--status S]
-  harbor start TASK | review TASK | done TASK [--confirm]
+                     [--priority low|medium|high|urgent] [--status S] [--over-limit]
+  harbor start TASK | review TASK | done TASK [--confirm] [--over-limit]
   harbor edit TASK [--title T] [--assignee me|none|NAME] [--due DATE|none]
-                   [--priority P] [--status S]
+                   [--priority P] [--status S] [--confirm] [--over-limit]
   harbor comment TASK "TEXT"
   harbor checkin "WHAT YOU'RE DOING" [--on-blocker]
-  harbor risk "TITLE" [--project P] [--impact 1-5] [--probability 1-5]
-  harbor issue "TITLE" [--project P]
+  harbor risk "TITLE" --project P|--program P [--impact 1-5] [--probability 1-5]
+                     [--owner NAME] [--due YYYY-MM-DD]
+  harbor issue "TITLE" --project P|--program P [--impact 1-5] [--owner NAME]
+                       [--due YYYY-MM-DD]
 
-  Every command takes --harbor NAME (when you're in more than one) and --json.
+  Every command takes --json, and --harbor NAME when you're in more than one harbor
+  (or set one with harbor use). harbor COMMAND --help shows just that command.
   Statuses: backlog, todo, doing, review, done.
   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.
@@ -120,21 +124,108 @@ const level = (v, name) => {
 };
 const nullable = (v) => (v === "none" ? null : v);
 
-/** Harbor's refusals are worded for agents; say which flag answers them. */
+/** Harbor's tool fields, as the CLI's flags. */
+const FLAG = {
+  due: "--due",
+  priority: "--priority",
+  status: "--status",
+  assignee: "--assignee",
+  title: "--title",
+  project: "--project",
+  program: "--program",
+  owner: "--owner",
+  impact: "--impact",
+  probability: "--probability",
+  query: "the words",
+  task: "the task",
+  note: "the check-in",
+  body: "the comment",
+};
+
+/** Harbor's refusals are worded for agents; say them as the commands and flags that answer them. */
 export function hint(message) {
   const said = message.replace(/\s*Ask the person;.*$/s, "");
   if (/confirmed: true/.test(message))
     return `${said}\nTo finish it anyway, run it again with --confirm.`;
   if (/overLimit: true/.test(message))
     return `${said}\nTo go past the limit, run it again with --over-limit.`;
-  return message;
+  const fit = /^Those arguments don't fit \w+: (.*)$/s.exec(message);
+  if (fit) {
+    // One line per flag: a bad date fails two checks that say the same thing.
+    const seen = new Map();
+    for (const issue of fit[1].split("; ")) {
+      const [path, ...why] = issue.split(": ");
+      const field = path.replace(/\.\d+$/, "");
+      const flag = FLAG[field] ?? `--${field}`;
+      if (!seen.has(flag)) seen.set(flag, why.join(": "));
+    }
+    return [...seen].map(([flag, why]) => `${flag}: ${why}`).join("\n");
+  }
+  return message
+    .replace(
+      /Say which one with harbor\.$/,
+      "Say which with --harbor NAME, or set one with harbor use NAME.",
+    )
+    .replace(/Find it with search_tasks\.$/, "Find it with harbor tasks.")
+    .replace(
+      /^This connection was allowed to read only\..*$/s,
+      "This sign-in can only read. To make changes, run harbor login again.",
+    )
+    .replace(
+      /^Say which project or program it belongs to\.$/,
+      "Say where it belongs: --project NAME or --program NAME.",
+    );
+}
+
+/** The lines of the help about one command, or null when it has none. */
+export function commandHelp(command) {
+  const lines = HELP.split("\n");
+  const picked = [];
+  for (let i = 0; i < lines.length; i++) {
+    const words = lines[i].trim().split(/\s+/);
+    const names = words.filter(
+      (_, j) => j > 0 && (words[j - 1] === "harbor" || words[j - 1] === "|"),
+    );
+    if (words[0] !== "harbor" || !names.includes(command)) continue;
+    picked.push(lines[i]);
+    // Its options carry on below it, further in.
+    while (lines[i + 1]?.startsWith("                  ") && /^\s+\[|^\s+--/.test(lines[i + 1]))
+      picked.push(lines[++i]);
+  }
+  if (picked.length === 0) return null;
+  const common = ["login", "logout", "use", "theme", "help", "app"].includes(command)
+    ? []
+    : ["", "  Also takes --json, and --harbor NAME when you're in more than one harbor."];
+  return [...picked, ...common].join("\n");
 }
 
+/** Room for --json and --harbor before the command too: `harbor --json mine`. */
+function commandFirst(argv) {
+  const front = [];
+  let i = 0;
+  while (argv[i] === "--json" || argv[i] === "--harbor" || argv[i]?.startsWith("--harbor=")) {
+    if (argv[i] === "--harbor") front.push(argv[i], argv[i + 1] ?? "");
+    else front.push(argv[i]);
+    i += argv[i] === "--harbor" ? 2 : 1;
+  }
+  return front.length && argv[i] ? [argv[i], ...front, ...argv.slice(i + 1)] : argv;
+}
+
+/** The command's arguments up to a bare --, where words stop being options. */
+const asksHelp = (rest) => {
+  const end = rest.indexOf("--");
+  return (end < 0 ? rest : rest.slice(0, end)).some((a) => a === "--help" || a === "-h");
+};
+
+const none = (positionals) => {
+  if (positionals.length) throw new HarborError(`Unexpected "${positionals.join(" ")}".`);
+};
+
 export async function run(argv, io = {}) {
   const out = io.out ?? ((s) => process.stdout.write(`${s}\n`));
   const env = io.env ?? process.env;
   const fetcher = io.fetch ?? fetch;
-  const [command, ...rest] = argv;
+  const [command, ...rest] = commandFirst(argv);
 
   if (command === "help" || command === "--help" || command === "-h") {
     const top = banner(io, env, ({ bold, dim }) => [
@@ -154,6 +245,16 @@ export async function run(argv, io = {}) {
     return 0;
   }
 
+  // `harbor done RR-4 --help` asks how, so nothing runs.
+  if (command && asksHelp(rest)) {
+    const help = commandHelp(command === "app" ? "" : command);
+    if (help === null && command !== "app") {
+      throw new HarborError(`No command "${command}". Run harbor help.`);
+    }
+    out(help ?? HELP);
+    return 0;
+  }
+
   // On its own in a terminal: the full-screen app. Piped or scripted: the help.
   if (!command || command === "app") {
     const terminal = io.terminal ?? Boolean(process.stdout.isTTY && process.stdin.isTTY);
@@ -193,7 +294,7 @@ export async function run(argv, io = {}) {
     await runApp({
       source: tokenSource({ creds, save: (c) => writeCredentials(c, env), fetcher }),
       fetcher,
-      harbor: values.harbor,
+      harbor: values.harbor ?? creds.harbor ?? undefined,
       theme: (await readSettings(env)).theme,
     });
     return 0;
@@ -202,6 +303,10 @@ export async function run(argv, io = {}) {
   if (command === "login") {
     const { values } = parseArgs(rest, { flags: ["read-only"], options: ["server"] });
     const server = (values.server ?? env.HARBOR_SERVER ?? DEFAULT_SERVER).replace(/\/$/, "");
+    if (!/^https?:\/\/[^/]/.test(server) || !URL.canParse(server)) {
+      throw new HarborError(`--server needs a web address, like ${DEFAULT_SERVER}.`);
+    }
+    const before = await readCredentials(env);
     const creds = await login({
       server,
       readOnly: Boolean(values["read-only"]),
@@ -213,6 +318,11 @@ export async function run(argv, io = {}) {
           openBrowser(url);
         }),
     });
+    // Signing in again keeps the harbor set with harbor use.
+    if (before?.harbor && before.server === server) {
+      creds.harbor = before.harbor;
+      creds.harborName = before.harborName ?? null;
+    }
     await writeCredentials(creds, env);
     const canWrite = creds.scope.split(" ").includes("harbor:write");
     const said = `Signed in to ${server}${canWrite ? "." : ", reading only."}`;
@@ -248,6 +358,7 @@ export async function run(argv, io = {}) {
   }
 
   if (command === "logout") {
+    none(parseArgs(rest, {}).positionals);
     await forgetCredentials(env);
     out(
       "Signed out on this machine. To end its access everywhere, disconnect Harbor CLI under Connected apps in Harbor's menu.",
@@ -272,16 +383,56 @@ export async function run(argv, io = {}) {
   const parse = (s) => {
     const p = parseArgs(rest, s);
     asJson = Boolean(p.values.json);
-    return { ...p, harbor: p.values.harbor };
+    return { ...p, harbor: p.values.harbor ?? creds.harbor ?? undefined };
   };
 
   switch (command) {
     case "harbors": {
-      parse(spec());
-      return call("list_harbors", {}, harbors);
+      none(parse(spec()).positionals);
+      return call("list_harbors", {}, (r) =>
+        creds.harbor
+          ? `${harbors(r)}\n\nCommands use ${creds.harborName ?? creds.harbor} (harbor use).`
+          : harbors(r),
+      );
+    }
+    case "use": {
+      const { positionals } = parse({ flags: ["json"], options: [] });
+      const wanted = positionals.join(" ").trim();
+      if (!wanted) {
+        out(
+          creds.harbor
+            ? plain(`Commands use ${creds.harborName ?? creds.harbor}.`)
+            : "No harbor set: commands use your only harbor, or the one --harbor names.",
+        );
+        return 0;
+      }
+      if (wanted.toLowerCase() === "none") {
+        await writeCredentials({ ...creds, harbor: null, harborName: null }, env);
+        out("Commands no longer pick a harbor for you.");
+        return 0;
+      }
+      const list = await client.call("list_harbors", {});
+      const key = wanted.toLowerCase();
+      const exact = list.harbors.filter(
+        (h) => h.id === wanted || h.name.trim().toLowerCase() === key,
+      );
+      const hits = exact.length
+        ? exact
+        : list.harbors.filter((h) => h.name.toLowerCase().includes(key));
+      if (hits.length === 0)
+        throw new HarborError(`No harbor matches "${wanted}". Run harbor harbors.`);
+      if (hits.length > 1) {
+        throw new HarborError(
+          `"${wanted}" matches more than one harbor: ${hits.map((h) => h.name).join(", ")}.`,
+        );
+      }
+      await writeCredentials({ ...creds, harbor: hits[0].id, harborName: hits[0].name }, env);
+      out(plain(`Commands now use ${hits[0].name}.`));
+      return 0;
     }
     case "mine": {
-      const { harbor } = parse(spec());
+      const { positionals, harbor } = parse(spec());
+      none(positionals);
       return call("my_work", { harbor }, (r) => myWork(r, opts));
     }
     case "tasks": {
@@ -295,7 +446,12 @@ export async function run(argv, io = {}) {
           query: positionals.join(" ") || undefined,
           project: values.project,
           assignee: values.assignee,
-          status: values.status ? values.status.split(",") : undefined,
+          status: values.status
+            ? values.status
+                .split(",")
+                .map((x) => x.trim())
+                .filter(Boolean)
+            : undefined,
           overdue: values.late || undefined,
         },
         (r) => taskList(r, opts),
@@ -422,8 +578,16 @@ export async function run(argv, io = {}) {
     case "risk":
     case "issue": {
       const { positionals, values, harbor } = parse(
-        spec([], ["project", "program", "owner", "impact", "probability", "due"]),
+        spec(
+          [],
+          ["project", "program", "owner", "impact", "due"].concat(
+            command === "risk" ? ["probability"] : [],
+          ),
+        ),
       );
+      if (!values.project && !values.program) {
+        throw new HarborError("Say where it belongs: --project NAME or --program NAME.");
+      }
       return call(
         "log_raid",
         {
@@ -434,7 +598,7 @@ export async function run(argv, io = {}) {
           program: values.program,
           owner: values.owner,
           impact: level(values.impact, "impact"),
-          probability: command === "risk" ? level(values.probability, "probability") : undefined,
+          probability: level(values.probability, "probability"),
           due: values.due,
         },
         (r) => `Logged the ${command} (${r.raised.id}).`,

package/lib/config.mjs

@@ -19,7 +19,12 @@ const file = (env) => join(configDir(env), "credentials.json");
 /** The saved sign-in, or null when there isn't one. */
 export async function readCredentials(env = process.env) {
   try {
-    return JSON.parse(await readFile(file(env), "utf8"));
+    const creds = JSON.parse(await readFile(file(env), "utf8"));
+    // A file that isn't a whole sign-in is no sign-in.
+    const whole = ["server", "accessToken", "tokenEndpoint"].every(
+      (k) => typeof creds?.[k] === "string" && creds[k],
+    );
+    return whole ? creds : null;
   } catch {
     return null;
   }

package/lib/errors.mjs

@@ -0,0 +1,28 @@
+/**
+ * What the CLI says when something stops a command: a HarborError is
+ * already worded for the person and printed as it is; anything else is
+ * unexpected and printed as "Something went wrong".
+ */
+export class HarborError extends Error {
+  // By name too: the full-screen app is bundled with its own copy of this class.
+  name = "HarborError";
+}
+
+/**
+ * fetch, with "the server isn't there" said plainly rather than as
+ * "fetch failed" (no network, a wrong --server, the server down).
+ * @param {typeof fetch} fetcher
+ * @param {string | URL} url
+ * @param {RequestInit} [init]
+ */
+export async function reach(fetcher, url, init) {
+  try {
+    return await fetcher(url, init);
+  } catch (err) {
+    if (/** @type {Error} */ (err)?.name === "AbortError") throw err;
+    const where = new URL(url).origin;
+    throw new HarborError(
+      `Can't reach ${where}. Check your connection, or the address you signed in with.`,
+    );
+  }
+}

package/lib/mcp.mjs

@@ -4,8 +4,9 @@
  * refreshed once and the call retried.
  */
 import { refresh } from "./auth.mjs";
+import { HarborError, reach } from "./errors.mjs";
 
-export class HarborError extends Error {}
+export { HarborError };
 
 const SKEW_MS = 60_000;
 
@@ -19,7 +20,7 @@ export function createClient({ creds, save, fetcher = fetch, now = Date.now }) {
   }
 
   async function post(body) {
-    return fetcher(new URL("/api/mcp", current.server), {
+    return reach(fetcher, new URL("/api/mcp", current.server), {
       method: "POST",
       headers: {
         "content-type": "application/json",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@harborppm/cli",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Harbor from the terminal: a full-screen app with everything, plus commands for scripts and agents.",
   "type": "module",
   "bin": {