@harborppm/cli 0.5.1 → 0.7.0

package/README.md

@@ -10,6 +10,18 @@ harbor mine                     # or one command at a time
 
 Needs Node 22 or later.
 
+## New to Harbor?
+
+You can start from the terminal. Harbor is free to start.
+
+```sh
+npm install -g @harborppm/cli
+harbor signup      # make your account in the browser (email or Google), then come back
+harbor             # name your harbor and its first project, and you're in
+```
+
+`harbor signup` opens Harbor's page on **Create**; confirm your email from the letter it sends when you get a moment. The first time you run `harbor` with no harbor yet, it asks for a name (Enter takes a suggestion) and, if you like, a first project, then opens on it. Joining a team's harbor instead? Open the invite they sent you, and `harbor` opens on their harbor.
+
 ## The full-screen app
 
 `harbor` on its own takes over the terminal, like `htop` or `lazygit`, and gives it back when you press `q`. It opens on Harbor's mark (the teal tile, the H and three boats, drawn in half blocks) while your harbor loads; after that the sidebar holds just the screens. Then:
@@ -43,7 +55,7 @@ It runs on the same engine as the website: health, task keys, limits and undo wo
 
 ## Signing in
 
-`harbor login` registers the CLI with Harbor and opens the same page Claude and other apps use: it names "Harbor CLI" and asks what to allow. Choose **Allow reading only** (or run `harbor login --read-only`) if it shouldn't change anything. The sign-in is saved in `~/.config/harbor/credentials.json`, readable only by you, and refreshes itself for 30 days.
+`harbor signup` is for a first visit: the same sign-in, with the page opened on making an account. `harbor login` registers the CLI with Harbor and opens the same page Claude and other apps use: it names "Harbor CLI" and asks what to allow. Choose **Allow reading only** (or run `harbor login --read-only`) if it shouldn't change anything. The sign-in is saved in `~/.config/harbor/credentials.json`, readable only by you, and refreshes itself for 30 days.
 
 `harbor logout` forgets it on this machine. To end its access everywhere, disconnect **Harbor CLI** under **Connected apps** in Harbor's menu.
 
@@ -51,22 +63,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

@@ -1,4 +1,5 @@
 // Built from src/tui by cli/build.mjs. Edit the source, not this file.
+import { createInterface } from "node:readline/promises";
 import { Box, Text, render, useApp, useInput, useWindowSize } from "ink";
 import React, { createContext, useContext, useEffect, useMemo, useState } from "react";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
@@ -1707,9 +1708,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 +1864,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];
 }
@@ -2907,7 +2921,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,
@@ -2994,7 +3011,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)}…`;
 }
@@ -8679,7 +8696,8 @@ function plainTransport(t) {
 		load: async (workspaceId) => plainDeep(await t.load(workspaceId)),
 		save: async (body) => plainDeep(await t.save(body)),
 		wait: async (workspaceId, since) => plainDeep(await t.wait(workspaceId, since)),
-		history: async (query) => plainDeep(await t.history(query))
+		history: async (query) => plainDeep(await t.history(query)),
+		create: async (name) => plainDeep(await t.create(name))
 	};
 }
 /** Harbor said no, or couldn't be reached (`offline`). */
@@ -8737,6 +8755,10 @@ function httpTransport(source, fetcher = fetch) {
 		history: (history) => post({
 			op: "history",
 			history
+		}),
+		create: (name) => post({
+			op: "create",
+			name
 		})
 	};
 }
@@ -8946,6 +8968,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";
@@ -9003,6 +9036,47 @@ function createUiStore() {
 	}));
 }
 
+//#endregion
+//#region src/lib/empty.ts
+/** What a new harbor is called until its owner names it: "Sam's harbor". */
+function suggestedHarborName(displayName, email) {
+	const first = (displayName || email || "").split(/[\s@]/)[0]?.trim();
+	if (!first) return "My harbor";
+	return `${first}'s harbor`;
+}
+
+//#endregion
+//#region src/tui/first-run.ts
+/**
+* A new account's first `harbor`: it isn't in a harbor yet, so the terminal
+* asks for a name (and, if they like, a first project) and makes the same
+* empty harbor the website's launch page makes, instead of sending them off
+* to the website.
+*/
+async function firstHarbor(deps) {
+	const fallback = suggestedHarborName(deps.account.name, deps.account.email);
+	deps.say("You're signed in, but you aren't in a harbor yet, so let's make yours.");
+	deps.say("Joining a team's harbor instead? Open the invite they sent you.\n");
+	const name = (await deps.ask(`Name your harbor (Enter for "${fallback}"): `)).trim() || fallback;
+	const project = (await deps.ask("Name your first project (Enter to skip): ")).trim() || null;
+	const { harbor } = await deps.transport.create(name.slice(0, 120));
+	return {
+		harbor,
+		project: project?.slice(0, 120) ?? null
+	};
+}
+/** The first project, in the new harbor's starter program, led by its owner. */
+function addFirstProject(store, name, accountId, today) {
+	const s = store.getState();
+	const program = s.programs[0];
+	if (!program) return null;
+	const me = s.people.find((p) => p.accountId === accountId) ?? s.people[0];
+	return commitCreate(store, "project", {
+		name,
+		ownerId: me?.id ?? ""
+	}, { programId: program.id }, today);
+}
+
 //#endregion
 //#region src/tui/main.tsx
 /**
@@ -9045,6 +9119,11 @@ async function startApp(deps, options = {}) {
 		instance.unmount();
 		throw err;
 	}
+	if (deps.firstRun) {
+		const project = deps.firstRun.project;
+		if (project) addFirstProject(store, project, account.id, today());
+		ui.setState({ notice: project ? `Your harbor is ready, with ${project} in it. n adds more, ? lists the keys.` : "Your harbor is ready. n adds a project, ? lists the keys." });
+	}
 	instance.rerender(/* @__PURE__ */ jsx(DepsProvider, {
 		value: {
 			store,
@@ -9063,25 +9142,81 @@ 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}".`);
+	const answer = await transport.harbors();
+	const account = answer.account;
+	let harbors = answer.harbors;
+	let firstRun;
+	let workspaceId;
+	if (harbors.length === 0) {
+		const terminal = terminalAsk();
+		try {
+			const made = await firstHarbor({
+				ask: terminal.ask,
+				say: (line) => process.stdout.write(`${line}\n`),
+				transport: plainTransport(transport),
+				account: plainDeep(account)
+			});
+			harbors = [made.harbor];
+			workspaceId = made.harbor.id;
+			firstRun = { project: made.project };
+		} finally {
+			terminal.close();
+		}
+	} else if (opts.harbor) workspaceId = harborNamed(harbors, opts.harbor).id;
 	const { instance } = await startApp({
 		transport,
 		account,
 		harbors,
-		workspaceId: pick?.id,
+		workspaceId,
 		splashMs: SPLASH_MS,
-		theme
+		theme,
+		firstRun
 	}, { alternateScreen: true });
 	await instance.waitUntilExit();
 }
+/** Questions asked on the plain terminal, before the app takes it over. Ctrl+C stops. */
+function terminalAsk() {
+	const rl = createInterface({
+		input: process.stdin,
+		output: process.stdout
+	});
+	let stop = () => {};
+	const stopped = new Promise((_, reject) => stop = reject);
+	stopped.catch(() => {});
+	const nothing = () => stop(new HarborError("Stopped. Nothing was made."));
+	rl.on("SIGINT", nothing);
+	rl.on("close", nothing);
+	return {
+		ask: (question) => Promise.race([rl.question(question), stopped]),
+		close: () => {
+			rl.off("close", nothing);
+			rl.close();
+		}
+	};
+}
 
 //#endregion
-export { SPLASH_MS, TransportError, httpTransport, runApp, startApp };
+export { SPLASH_MS, TransportError, firstHarbor, 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");
 }
 
@@ -89,16 +90,23 @@ export async function listenForCode(state, { timeoutMs = 5 * 60_000 } = {}) {
 
 /**
  * The whole sign-in. `open(url)` shows the asking page (a browser, or a test
- * driving one). Returns credentials to save.
+ * driving one). `signUp` opens it on making an account. Returns credentials to save.
  */
-export async function login({ server, readOnly = false, open, fetcher = fetch, now = Date.now }) {
+export async function login({
+  server,
+  readOnly = false,
+  signUp = false,
+  open,
+  fetcher = fetch,
+  now = Date.now,
+}) {
   const meta = await discover(server, fetcher);
   const state = b64url(randomBytes(16));
   const { verifier, challenge } = pkcePair();
   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 +128,14 @@ 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}`,
+    // OpenID's way to say "new here": Harbor's page opens on Create.
+    ...(signUp ? { prompt: "create" } : {}),
   }).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 +165,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

@@ -24,27 +24,32 @@ import { jsonText, plain } from "./plain.mjs";
 export const HELP = `harbor: Harbor from the terminal
 
   harbor                                      the full-screen app: everything, with the keyboard
+  harbor signup [--server URL]                new to Harbor: make an account (opens your browser)
   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 +125,112 @@ 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.",
+    )
+    .replace(
+      /^You don't belong to a harbor yet\..*$/s,
+      "You aren't in a harbor yet. Run harbor to make one, or open the invite a team sent you.",
+    );
 }
 
+/** 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 = ["signup", "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 +250,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,37 +299,57 @@ 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;
   }
 
-  if (command === "login") {
-    const { values } = parseArgs(rest, { flags: ["read-only"], options: ["server"] });
+  if (command === "login" || command === "signup") {
+    const signUp = command === "signup";
+    const { values } = parseArgs(rest, {
+      flags: signUp ? [] : ["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"]),
+      signUp,
       fetcher,
       open:
         io.open ??
         ((url) => {
-          out(`Opening your browser to sign in. If it doesn't open, go to:\n\n  ${url}\n`);
+          out(
+            signUp
+              ? `Opening your browser to make your Harbor account. If it doesn't open, go to:\n\n  ${url}\n`
+              : `Opening your browser to sign in (new to Harbor? choose Create there). If it doesn't open, go to:\n\n  ${url}\n`,
+          );
           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."}`;
+    const next = signUp ? "Next: run harbor, and it helps you make your first harbor." : null;
     const welcome = banner(io, env, ({ bold, dim }) => [
       bold("Welcome aboard."),
       said,
+      ...(next ? [next] : []),
       "",
       dim("harbor        the full-screen app"),
       dim("harbor help   every command"),
     ]);
-    out(welcome ?? said);
+    out(welcome ?? (next ? `${said}\n${next}` : said));
     return 0;
   }
 
@@ -248,6 +374,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.",
@@ -256,7 +383,8 @@ export async function run(argv, io = {}) {
   }
 
   const creds = await readCredentials(env);
-  if (!creds) throw new HarborError("Not signed in. Run harbor login.");
+  if (!creds)
+    throw new HarborError("Not signed in. Run harbor login, or harbor signup if you're new.");
   const client = createClient({ creds, save: (c) => writeCredentials(c, env), fetcher });
   const opts = { today: todayLocal() };
 
@@ -272,16 +400,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 +463,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 +595,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 +615,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/format.mjs

@@ -52,7 +52,7 @@ export function taskList(r, opts) {
 
 export function harbors(r) {
   const list = r.harbors ?? [];
-  if (!list.length) return "You aren't in any harbor yet.";
+  if (!list.length) return "You aren't in any harbor yet. Run harbor to make one.";
   return list.map((h) => `${h.id}  ${h.name}${h.role ? `  (${h.role})` : ""}`).join("\n");
 }
 

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,7 +1,19 @@
 {
   "name": "@harborppm/cli",
-  "version": "0.5.1",
+  "version": "0.7.0",
   "description": "Harbor from the terminal: a full-screen app with everything, plus commands for scripts and agents.",
+  "keywords": [
+    "harbor",
+    "project-management",
+    "portfolio-management",
+    "ppm",
+    "kanban",
+    "tasks",
+    "cli",
+    "tui",
+    "terminal",
+    "mcp"
+  ],
   "type": "module",
   "bin": {
     "harbor": "bin/harbor.mjs"