@harborppm/cli 0.3.0 → 0.5.0

package/README.md

@@ -12,7 +12,7 @@ Needs Node 22 or later.
 
 ## 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, then:
+`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:
 
 1. **Today**: what's on you, late first; who's waiting on you; your risks and issues.
 2. **Inbox**: the same pings as the website: waiting on you, sign-offs, mentions. Enter opens one; it's marked read.
@@ -27,8 +27,18 @@ A task changes in place too: title, status, owner, due date (`2026-10-14`, `toda
 
 Keys: `↑↓` (or `j k`) and `←→` (or `h l`) move, Enter opens, Esc goes back, `:` finds anything (a screen, "new project", a project or program by name), `/` finds a task by its key or words, `n` makes something new, `e` changes what's open, `[` `]` move a card a column, `x` marks it done, `d` deletes (it asks first), `u` undoes your last change, `H` switches harbor, `?` lists them all.
 
+It has colours for dark terminals and for light ones, and picks by asking the terminal for its background (or reading `COLORFGBG`); a terminal that doesn't say gets the dark ones. `harbor theme light` or `harbor theme dark` settles it, `harbor theme auto` goes back to asking, and `HARBOR_THEME` overrides it for one run.
+
 `harbor help` shows the mark too, in a terminal with colour; piped, or with `NO_COLOR` set, it's plain text. `harbor --version` says which version you have.
 
+## Staying up to date
+
+npm doesn't update a global install by itself, so once a day `harbor` asks npm whether a newer version is out, alongside whatever command you ran, and says so in one line when there is (`npm install -g @harborppm/cli@latest` updates it). It says nothing in scripts, pipes or CI; set `HARBOR_NO_UPDATE_CHECK=1` (or `NO_UPDATE_NOTIFIER=1`) to turn it off.
+
+## Text from others
+
+Task titles, names and notes can come from an intake form, a GitHub pull request or anyone in a harbor. Before the commands or the app show them, `harbor` takes out the control characters a terminal would act on (escape sequences, backspaces, text-direction overrides), so a title can't set your clipboard, retitle the window or hide what's around it. `--json` keeps the data exact, with those characters written as `\u` escapes.
+
 It runs on the same engine as the website: health, task keys, limits and undo work the same way, changes save as you go (the header says when, and holds them while you're offline), and changes anyone makes on the website or elsewhere show up within a couple of seconds. It needs full access, which `harbor login` asks for by name; an older sign-in is asked again the first time.
 
 ## Signing in

package/bin/harbor.mjs

@@ -1,16 +1,33 @@
 #!/usr/bin/env node
-import { run } from "../lib/cli.mjs";
+import { VERSION, run } from "../lib/cli.mjs";
 import { HarborError } from "../lib/mcp.mjs";
+import { plain } from "../lib/plain.mjs";
+import { updateNotice } from "../lib/update.mjs";
 
-run(process.argv.slice(2)).then(
-  (code) => process.exit(code),
-  (err) => {
+const argv = process.argv.slice(2);
+// Asked alongside the command, so it costs nothing extra (see update.mjs).
+const notice = argv.includes("--json")
+  ? Promise.resolve(null)
+  : updateNotice({ version: VERSION }).catch(() => null);
+const tell = async () => {
+  const line = await notice;
+  if (line) process.stderr.write(`\n${line}\n`);
+};
+
+run(argv).then(
+  async (code) => {
+    await tell();
+    process.exit(code);
+  },
+  async (err) => {
     const known =
       err instanceof 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(
-      `${known ? err.message : `Something went wrong: ${err?.message ?? err}`}\n`,
+      `${plain(known ? err.message : `Something went wrong: ${err?.message ?? err}`)}\n`,
     );
+    await tell();
     process.exit(1);
   },
 );

package/dist/app.mjs

@@ -2077,25 +2077,62 @@ function forecastLine(f) {
 
 //#endregion
 //#region src/tui/theme.ts
-const theme = {
-	accent: "#3dbcab",
-	coral: "#e0714f",
-	muted: "gray",
-	selected: "#3dbcab"
-};
-const HEALTH_COLOR = {
-	"on-track": "green",
-	"at-risk": "yellow",
-	"off-track": "red",
-	paused: "gray",
-	done: "cyan"
+/**
+* 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
+* and coral, and status in hues dark enough for text on white (4.5:1 or more).
+*/
+const PALETTES = {
+	dark: {
+		accent: "#3dbcab",
+		coral: "#e0714f",
+		muted: "gray",
+		selected: "#3dbcab",
+		border: "gray",
+		good: "green",
+		warn: "yellow",
+		bad: "red",
+		done: "cyan"
+	},
+	light: {
+		accent: "#0f6e64",
+		coral: "#b8432c",
+		muted: "#5f5e58",
+		selected: "#0f6e64",
+		border: "#a8a69e",
+		good: "#1f7a3a",
+		warn: "#8a5a0a",
+		bad: "#b8432c",
+		done: "#146c6b"
+	}
 };
-const PRIORITY_COLOR = {
-	urgent: "red",
-	high: "#e0714f",
-	medium: void 0,
-	low: "gray"
+const theme = {
+	name: "dark",
+	...PALETTES.dark
 };
+const HEALTH_COLOR = {};
+const PRIORITY_COLOR = {};
+/** Switch every colour to one set. Call before the app draws. */
+function applyTheme(name) {
+	Object.assign(theme, {
+		name,
+		...PALETTES[name]
+	});
+	Object.assign(HEALTH_COLOR, {
+		"on-track": theme.good,
+		"at-risk": theme.warn,
+		"off-track": theme.bad,
+		paused: theme.muted,
+		done: theme.done
+	});
+	Object.assign(PRIORITY_COLOR, {
+		urgent: theme.bad,
+		high: theme.coral,
+		medium: void 0,
+		low: theme.muted
+	});
+}
+applyTheme("dark");
 
 //#endregion
 //#region src/tui/ui.tsx
@@ -2118,7 +2155,7 @@ function TextField({ label, initial = "", placeholder, hint, onSubmit, onCancel
 	return /* @__PURE__ */ jsxs(Box, {
 		flexDirection: "column",
 		borderStyle: "round",
-		borderColor: theme.accent,
+		borderColor: theme.border,
 		paddingX: 1,
 		children: [
 			/* @__PURE__ */ jsx(Text, {
@@ -2152,7 +2189,7 @@ function Picker({ title, choices, initial = 0, rows = 10, onPick, onCancel }) {
 	return /* @__PURE__ */ jsxs(Box, {
 		flexDirection: "column",
 		borderStyle: "round",
-		borderColor: theme.accent,
+		borderColor: theme.border,
 		paddingX: 1,
 		children: [
 			/* @__PURE__ */ jsx(Text, {
@@ -2221,7 +2258,6 @@ function Hints({ keys }) {
 		children: keys.map(([k, label], i) => /* @__PURE__ */ jsxs(Text, { children: [
 			i > 0 ? "  " : "",
 			/* @__PURE__ */ jsx(Text, {
-				color: theme.accent,
 				bold: true,
 				children: k
 			}),
@@ -2249,7 +2285,6 @@ function Heading({ children, right }) {
 		justifyContent: "space-between",
 		children: [/* @__PURE__ */ jsx(Text, {
 			bold: true,
-			color: theme.accent,
 			children
 		}), right ? /* @__PURE__ */ jsx(Text, {
 			color: theme.muted,
@@ -2344,7 +2379,7 @@ function DetailPanel({ title, subtitle, fields, width, height, keys = {}, hints,
 		width,
 		height,
 		borderStyle: "round",
-		borderColor: theme.accent,
+		borderColor: theme.border,
 		paddingX: 1,
 		children: [
 			/* @__PURE__ */ jsx(Text, {
@@ -2687,7 +2722,7 @@ function TaskLine({ task, projects, people, today, selected, width, showProject
 				"  ",
 				/* @__PURE__ */ jsx(PriorityMark, { priority: task.priority }),
 				task.dueDate ? /* @__PURE__ */ jsxs(Text, {
-					color: late ? "red" : theme.muted,
+					color: late ? theme.bad : theme.muted,
 					children: [
 						" ",
 						late ? "late · " : "",
@@ -2695,7 +2730,7 @@ function TaskLine({ task, projects, people, today, selected, width, showProject
 					]
 				}) : null,
 				blocked ? /* @__PURE__ */ jsx(Text, {
-					color: "yellow",
+					color: theme.warn,
 					children: " waits"
 				}) : null,
 				who ? /* @__PURE__ */ jsxs(Text, {
@@ -2849,7 +2884,7 @@ function HistoryView({ active, width, height, go }) {
 				children: "Loading…"
 			}) : null,
 			state === "failed" ? /* @__PURE__ */ jsx(Text, {
-				color: "red",
+				color: theme.bad,
 				children: "Couldn’t load History. It tries again after the next save."
 			}) : null,
 			state === "ready" && rows.length === 0 ? /* @__PURE__ */ jsx(Text, {
@@ -3496,7 +3531,7 @@ const LOGO = [
 	"..TTTTTTTTTTTTTTTTTTTT..",
 	"...TTTTTTTTTTTTTTTTTT..."
 ];
-/** 16 by 16, for narrow places. */
+/** 16 by 16, for the keys overlay. */
 const LOGO_SMALL = [
 	"..TTTTTTTTTTTT..",
 	".TTTTTTTTTTTTTT.",
@@ -3681,7 +3716,7 @@ function SearchBox({ width, onOpen, onClose }) {
 		flexDirection: "column",
 		width,
 		borderStyle: "round",
-		borderColor: theme.accent,
+		borderColor: theme.border,
 		paddingX: 1,
 		children: [
 			/* @__PURE__ */ jsxs(Text, { children: [
@@ -3818,6 +3853,12 @@ const HELP = [
 	["r", "retry saving now"],
 	["q", "quit (saves first)"]
 ];
+/**
+* The mark sits beside the keys only when both fit: the longest line, a gap,
+* the 16-pixel mark, and the box's border and padding. Narrower, the lines
+* would wrap and split the mark.
+*/
+const HELP_WITH_MARK = 11 + Math.max(...HELP.map(([, what]) => what.length)) + 2 + LOGO_SMALL[0].length + 4;
 function Help({ width, onClose }) {
 	useInput((input, key) => {
 		if (key.escape || key.return || input === "?" || input === "q") onClose();
@@ -3825,7 +3866,7 @@ function Help({ width, onClose }) {
 	return /* @__PURE__ */ jsxs(Box, {
 		width,
 		borderStyle: "round",
-		borderColor: theme.accent,
+		borderColor: theme.border,
 		paddingX: 1,
 		children: [/* @__PURE__ */ jsxs(Box, {
 			flexDirection: "column",
@@ -3845,7 +3886,7 @@ function Help({ width, onClose }) {
 					children: "Everything saves as you go, and shows on the website for everyone."
 				})
 			]
-		}), width >= 90 ? /* @__PURE__ */ jsxs(Box, {
+		}), width >= HELP_WITH_MARK ? /* @__PURE__ */ jsxs(Box, {
 			flexDirection: "column",
 			alignItems: "center",
 			marginLeft: 2,
@@ -3927,7 +3968,7 @@ function Palette({ width, base, open, onClose }) {
 		flexDirection: "column",
 		width,
 		borderStyle: "round",
-		borderColor: theme.accent,
+		borderColor: theme.border,
 		paddingX: 1,
 		children: [
 			/* @__PURE__ */ jsxs(Text, { children: [
@@ -4317,7 +4358,7 @@ function MilestonePanel({ id, width, height, go, onClose }) {
 		{
 			label: "Due",
 			value: `${shortDay(milestone.dueDate, today())}${late ? " (late)" : ""}`,
-			color: late ? "red" : void 0,
+			color: late ? theme.bad : void 0,
 			edit: {
 				kind: "date",
 				initial: milestone.dueDate,
@@ -4780,7 +4821,7 @@ function ProgramView({ programId, active, width, height, go, onBack }) {
 								}) : m.name,
 								" ",
 								/* @__PURE__ */ jsxs(Text, {
-									color: late ? "red" : theme.muted,
+									color: late ? theme.bad : theme.muted,
 									children: [late ? "late · " : "", shortDay(m.dueDate, today())]
 								}),
 								m.approverId ? /* @__PURE__ */ jsx(Text, {
@@ -5049,7 +5090,7 @@ function ProjectView({ projectId, active, width, height, go, onBack }) {
 						flexDirection: "column",
 						width: w,
 						borderStyle: "round",
-						borderColor: on ? theme.accent : "gray",
+						borderColor: on ? theme.accent : theme.border,
 						paddingX: 1,
 						children: [
 							/* @__PURE__ */ jsxs(Text, {
@@ -5060,7 +5101,7 @@ function ProjectView({ projectId, active, width, height, go, onBack }) {
 									c.label.toUpperCase(),
 									" ",
 									/* @__PURE__ */ jsxs(Text, {
-										color: over ? "red" : theme.muted,
+										color: over ? theme.bad : theme.muted,
 										children: [c.tasks.length, c.limit != null ? `/${c.limit}` : ""]
 									})
 								]
@@ -5146,11 +5187,11 @@ function Card({ taskKey, title, owner, due, late, waits, priority, selected }) {
 					children: [" ", owner]
 				}) : null,
 				due ? /* @__PURE__ */ jsxs(Text, {
-					color: late ? "red" : selected ? void 0 : theme.muted,
+					color: late ? theme.bad : selected ? void 0 : theme.muted,
 					children: [" ", due]
 				}) : null,
 				waits ? /* @__PURE__ */ jsx(Text, {
-					color: "yellow",
+					color: theme.warn,
 					children: " waits"
 				}) : null
 			]
@@ -5168,7 +5209,7 @@ function Card({ taskKey, title, owner, due, late, waits, priority, selected }) {
 /** A project's money: budget, spent, what's left and the forecast, then the ledger. */
 function BudgetPane({ project, spendEntries, at, active, height, today }) {
 	const b = budgetOf({ spendEntries }, project, /* @__PURE__ */ new Date(`${today}T12:00:00`));
-	const tone = b.forecast?.tone === "over" ? "red" : b.forecast?.tone === "tight" ? "yellow" : "green";
+	const tone = b.forecast?.tone === "over" ? theme.bad : b.forecast?.tone === "tight" ? theme.warn : theme.good;
 	return /* @__PURE__ */ jsxs(Box, {
 		flexDirection: "column",
 		height,
@@ -5196,7 +5237,7 @@ function BudgetPane({ project, spendEntries, at, active, height, today }) {
 				" ",
 				/* @__PURE__ */ jsxs(Text, {
 					bold: true,
-					color: b.left < 0 ? "red" : void 0,
+					color: b.left < 0 ? theme.bad : void 0,
 					children: [money(Math.abs(b.left)), b.left < 0 ? " over" : ""]
 				})
 			] }),
@@ -5536,7 +5577,7 @@ function TaskPanel({ taskId, width, height, go, onClose }) {
 		width,
 		height,
 		borderStyle: "round",
-		borderColor: theme.accent,
+		borderColor: theme.border,
 		paddingX: 1,
 		children: [
 			/* @__PURE__ */ jsxs(Text, {
@@ -5553,7 +5594,7 @@ function TaskPanel({ taskId, width, height, go, onClose }) {
 						children: task.title
 					}),
 					viewOnly ? /* @__PURE__ */ jsx(Text, {
-						color: "yellow",
+						color: theme.warn,
 						children: " view only"
 					}) : null
 				]
@@ -5573,7 +5614,7 @@ function TaskPanel({ taskId, width, height, go, onClose }) {
 				]
 			}, f.field)),
 			waits.length > 0 ? /* @__PURE__ */ jsxs(Text, {
-				color: "yellow",
+				color: theme.warn,
 				wrap: "truncate-end",
 				children: [
 					"  ",
@@ -5757,7 +5798,7 @@ function TodayView({ active, width, height, go }) {
 					children: [
 						"  ",
 						/* @__PURE__ */ jsx(Text, {
-							color: r.kind === "risk" ? "yellow" : r.kind === "issue" ? "red" : theme.muted,
+							color: r.kind === "risk" ? theme.warn : r.kind === "issue" ? theme.bad : theme.muted,
 							children: r.kind
 						}),
 						" ",
@@ -5811,12 +5852,15 @@ const NAV = [
 		label: "History"
 	}
 ];
+/** The sidebar's width: its longest line ("8 History", ": Anything") with room either side. */
+const NAV_WIDTH = 15;
+/** What the corner says about saving, and in which of the theme's colours. */
 const SAVE_LABEL = {
-	saved: ["● saved", "green"],
-	pending: ["● saving soon", "yellow"],
-	saving: ["● saving…", "yellow"],
-	retrying: ["● not saved, retrying", "red"],
-	offline: ["● offline, will save", "red"]
+	saved: ["● saved", "good"],
+	pending: ["● saving soon", "warn"],
+	saving: ["● saving…", "warn"],
+	retrying: ["● not saved, retrying", "bad"],
+	offline: ["● offline, will save", "bad"]
 };
 function App({ ui }) {
 	const { store, sync, account, harbors, today } = useDeps();
@@ -6004,10 +6048,10 @@ function App({ ui }) {
 		if (input === "u" && !store.undoLast()) notify("Nothing to undo.");
 	}, { isActive: !covered && panel !== null });
 	const bodyHeight = Math.max(8, rows - 1 - 2);
-	const navWidth = 14;
-	const mainWidth = Math.max(30, columns - navWidth - 1);
+	const mainWidth = Math.max(30, columns - NAV_WIDTH - 1);
 	const mainActive = focus === "main" && !covered && panel === null;
-	const [saveText, saveColor] = SAVE_LABEL[save];
+	const [saveText, saveTone] = SAVE_LABEL[save];
+	const saveColor = theme[saveTone];
 	const viewProps = {
 		active: mainActive,
 		width: mainWidth,
@@ -6238,7 +6282,7 @@ function App({ ui }) {
 							children: harborName ?? "…"
 						}),
 						viewOnly ? /* @__PURE__ */ jsx(Text, {
-							color: "yellow",
+							color: theme.warn,
 							children: " · view only"
 						}) : null
 					]
@@ -6254,13 +6298,13 @@ function App({ ui }) {
 				height: bodyHeight,
 				children: [/* @__PURE__ */ jsxs(Box, {
 					flexDirection: "column",
-					width: navWidth,
+					width: NAV_WIDTH,
 					paddingX: 1,
 					borderStyle: "single",
 					borderTop: false,
 					borderBottom: false,
 					borderLeft: false,
-					borderColor: focus === "nav" ? theme.accent : "gray",
+					borderColor: focus === "nav" ? theme.accent : theme.border,
 					children: [
 						NAV.map((x, i) => {
 							const on = x.screen === screen && stack.length === 0;
@@ -7017,12 +7061,24 @@ function sessionSlice({ set, get, write }) {
 			keepInterval: k.interval,
 			stripeReady: k.stripe
 		}),
-		ensureAccountPerson: ({ accountId, name }) => {
+		ensureAccountPerson: ({ accountId, name, personId }) => {
 			const hit = get().people.find((p) => p.accountId === accountId);
 			if (hit) {
 				if (get().currentUserId !== hit.id) set({ currentUserId: hit.id });
 				return hit.id;
 			}
+			const named = personId ? get().people.find((p) => p.id === personId && !p.accountId) : null;
+			if (named) {
+				set({
+					people: get().people.map((p) => p.id === named.id ? {
+						...p,
+						accountId
+					} : p),
+					currentUserId: named.id
+				});
+				get().log("came aboard", "/people");
+				return named.id;
+			}
 			const used = new Set(get().people.map((p) => p.swatch));
 			const swatch = SWATCHES.find((s) => !used.has(s)) ?? "pine";
 			const id = uid("p");
@@ -7383,7 +7439,8 @@ function hierarchySlice({ get, write }) {
 			write({
 				programs: add(state.programs, rows.programs),
 				projects: add(state.projects, rows.projects),
-				tasks: add(state.tasks, rows.tasks)
+				tasks: add(state.tasks, rows.tasks),
+				people: add(state.people, rows.people)
 			});
 			const n = rows.tasks?.length ?? 0;
 			get().log(`imported ${n} task${n === 1 ? "" : "s"} from a spreadsheet`);
@@ -7393,12 +7450,18 @@ function hierarchySlice({ get, write }) {
 			const gone = {
 				programs: new Set(ids.programs ?? []),
 				projects: new Set(ids.projects ?? []),
-				tasks: new Set(ids.tasks ?? [])
+				tasks: new Set(ids.tasks ?? []),
+				people: new Set(ids.people ?? [])
 			};
+			const tasks = state.tasks.filter((r) => !gone.tasks.has(r.id));
+			if (gone.people.size) {
+				for (const t of tasks) if (t.assigneeId) gone.people.delete(t.assigneeId);
+			}
 			write({
 				programs: state.programs.filter((r) => !gone.programs.has(r.id)),
 				projects: state.projects.filter((r) => !gone.projects.has(r.id)),
-				tasks: state.tasks.filter((r) => !gone.tasks.has(r.id)),
+				tasks,
+				people: gone.people.size ? state.people.filter((r) => !gone.people.has(r.id)) : state.people,
 				selectedTaskId: gone.tasks.has(state.selectedTaskId ?? "") ? null : state.selectedTaskId
 			});
 		},
@@ -8560,8 +8623,62 @@ function retryDelay(attempt) {
 	return Math.min(3e4, 2e3 * 2 ** Math.max(0, attempt));
 }
 
+//#endregion
+//#region cli/lib/plain.mjs
+/**
+* Text from a harbor, made safe to show in a terminal. A task title can come
+* from a public intake form, a GitHub pull request or any member, and a
+* terminal acts on control characters it's sent: an escape sequence in a
+* title could set the clipboard, retitle the window or hide what's around
+* it. So they're taken out before anything is printed: the C0 and C1
+* controls (tab and newline stay), DEL, and the bidirectional overrides that
+* make text read in a different order than it's stored.
+*/
+const UNSAFE = /[\u0000-\u0008\u000b-\u001f\u007f-\u009f‪-‮⁦-⁩]/g;
+/** @param {string} text */
+function plain(text) {
+	return text.replace(UNSAFE, "");
+}
+/**
+* Every string in a value made plain: what the full-screen app takes in from
+* Harbor, before any of it reaches the screen.
+* @template T
+* @param {T} value
+* @returns {T}
+*/
+function plainDeep(value) {
+	if (typeof value === "string") return plain(value);
+	if (Array.isArray(value)) return value.map(plainDeep);
+	if (value && typeof value === "object") {
+		/** @type {Record<string, unknown>} */
+		const out = {};
+		for (const [k, v] of Object.entries(value)) out[k] = plainDeep(v);
+		return out;
+	}
+	return value;
+}
+
 //#endregion
 //#region src/tui/engine/transport.ts
+/**
+* How the terminal app talks to Harbor: POSTs to /api/app with the bearer
+* token `harbor login` saved (mcp/app.server.ts on the other end). An
+* expired token is renewed once and the request retried.
+*/
+/**
+* The same transport with every answer made plain (cli/lib/plain.mjs):
+* titles, names and notes can come from intake forms, GitHub or anyone in
+* the harbor, and a terminal acts on control characters they carry.
+*/
+function plainTransport(t) {
+	return {
+		harbors: async () => plainDeep(await t.harbors()),
+		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))
+	};
+}
 /** Harbor said no, or couldn't be reached (`offline`). */
 var TransportError = class extends Error {
 	status;
@@ -8826,6 +8943,53 @@ function createSync(opts) {
 	};
 }
 
+//#endregion
+//#region src/tui/theme-detect.ts
+const isThemeSetting = (v) => v === "auto" || v === "light" || v === "dark";
+/** COLORFGBG is "fg;bg" (sometimes "fg;x;bg"): background 7 or 15 is a light terminal. */
+function themeFromColorFgBg(value) {
+	const bg = value?.split(";").at(-1);
+	if (!bg || !/^\d+$/.test(bg)) return null;
+	return bg === "7" || bg === "15" ? "light" : "dark";
+}
+/** A terminal's answer to OSC 11, like "\x1b]11;rgb:ffff/ffff/ffff\x07": light when its luminance is over half. */
+function themeFromReply(reply) {
+	const m = /rgba?:([0-9a-f]+)\/([0-9a-f]+)\/([0-9a-f]+)/i.exec(reply);
+	if (!m) return null;
+	const [r, g, b] = m.slice(1, 4).map((hex) => parseInt(hex, 16) / (16 ** hex.length - 1));
+	return .2126 * r + .7152 * g + .0722 * b > .5 ? "light" : "dark";
+}
+/** Ask the terminal for its background colour; null when it doesn't say in time. */
+function askBackground(stdin, stdout, ms = 300) {
+	if (!stdin.isTTY || !stdout.isTTY || typeof stdin.setRawMode !== "function") return Promise.resolve(null);
+	return new Promise((resolve) => {
+		let reply = "";
+		const done = (theme) => {
+			clearTimeout(timer);
+			stdin.off("data", onData);
+			stdin.setRawMode(false);
+			stdin.pause();
+			resolve(theme);
+		};
+		const onData = (chunk) => {
+			reply += chunk.toString();
+			if (/\x07|\x1b\\/.test(reply)) done(themeFromReply(reply));
+		};
+		const timer = setTimeout(() => done(null), ms);
+		stdin.setRawMode(true);
+		stdin.resume();
+		stdin.on("data", onData);
+		stdout.write("\x1B]11;?\x1B\\");
+	});
+}
+/** The set to draw with, from the saved setting, the environment, then the terminal itself. */
+async function pickTheme(setting, env = process.env, ask = () => askBackground(process.stdin, process.stdout)) {
+	const fromEnv = env.HARBOR_THEME?.toLowerCase();
+	const chosen = isThemeSetting(fromEnv) ? fromEnv : setting;
+	if (chosen === "light" || chosen === "dark") return chosen;
+	return themeFromColorFgBg(env.COLORFGBG) ?? await ask() ?? "dark";
+}
+
 //#endregion
 //#region src/tui/ui-state.ts
 /** What the shell shows beside the harbor: the save state and the latest notice. */
@@ -8844,30 +9008,36 @@ function createUiStore() {
 * CLI package's own dependencies.
 */
 const today = () => format(/* @__PURE__ */ new Date(), "yyyy-MM-dd");
+/** How long `harbor` shows its splash at the least, however fast the harbor loads. */
+const SPLASH_MS = 1200;
 /**
 * Open the app on a transport that's already signed in: the harbor used
 * most, the store and the sync loop, drawn with Ink.
 */
 async function startApp(deps, options = {}) {
+	applyTheme(deps.theme ?? "dark");
+	const transport = plainTransport(deps.transport);
+	const account = plainDeep(deps.account);
+	const harbors = plainDeep(deps.harbors);
 	const ui = createUiStore();
 	const store = createAppStore((n) => ui.setState({ notice: n.kind === "view-only" ? "You can only view this harbor, so that wasn't changed." : n.kept > 0 ? `Undid ${n.label}. ${n.kept} field${n.kept === 1 ? "" : "s"} someone else changed since stayed theirs.` : `Undid ${n.label}.` }));
 	const sync = createSync({
 		store,
-		transport: deps.transport,
+		transport,
 		account: {
-			id: deps.account.id,
-			name: deps.account.name || deps.account.email
+			id: account.id,
+			name: account.name || account.email
 		},
 		onState: (save) => ui.setState({ save }),
 		onNotice: (notice) => ui.setState({ notice })
 	});
-	const opening = deps.workspaceId ? deps.harbors.find((h) => h.id === deps.workspaceId) : deps.harbors.length === 1 ? deps.harbors[0] : void 0;
+	const opening = deps.workspaceId ? harbors.find((h) => h.id === deps.workspaceId) : harbors.length === 1 ? harbors[0] : void 0;
 	const instance = render(/* @__PURE__ */ jsx(Splash, { opening: opening?.name }), {
 		exitOnCtrlC: false,
 		...options
 	});
 	try {
-		await sync.open(deps.workspaceId);
+		await Promise.all([sync.open(deps.workspaceId), new Promise((r) => setTimeout(r, deps.splashMs ?? 0))]);
 	} catch (err) {
 		instance.unmount();
 		throw err;
@@ -8876,9 +9046,9 @@ async function startApp(deps, options = {}) {
 		value: {
 			store,
 			sync,
-			transport: deps.transport,
-			account: deps.account,
-			harbors: deps.harbors,
+			transport,
+			account,
+			harbors,
 			today
 		},
 		children: /* @__PURE__ */ jsx(App, { ui })
@@ -8892,6 +9062,7 @@ async function startApp(deps, options = {}) {
 }
 /** `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.");
@@ -8902,10 +9073,12 @@ async function runApp(opts) {
 		transport,
 		account,
 		harbors,
-		workspaceId: pick?.id
+		workspaceId: pick?.id,
+		splashMs: SPLASH_MS,
+		theme
 	}, { alternateScreen: true });
 	await instance.waitUntilExit();
 }
 
 //#endregion
-export { TransportError, httpTransport, runApp, startApp };
+export { SPLASH_MS, TransportError, httpTransport, runApp, startApp };

package/lib/app.mjs

@@ -14,9 +14,17 @@ export const hasFullAccess = (creds) => Boolean(creds?.scope?.split(" ").include
 /** The app's token source: the saved tokens, renewed (and saved again) when they run out. */
 export function tokenSource({ creds, save, fetcher = fetch, now = Date.now }) {
   let current = creds;
-  const renew = async () => {
-    current = await refresh(current, { fetcher, now });
-    await save(current);
+  // One renewal at a time: the app's save and live wait often find the token
+  // spent together, and a refresh token is good for one renewal.
+  let renewing = null;
+  const renew = () => {
+    renewing ??= (async () => {
+      current = await refresh(current, { fetcher, now });
+      await save(current);
+    })().finally(() => {
+      renewing = null;
+    });
+    return renewing;
   };
   return {
     server: current.server,

package/lib/cli.mjs

@@ -8,10 +8,18 @@ import { readFileSync } from "node:fs";
 import { parseArgs } from "./args.mjs";
 import { hasFullAccess, loadApp, tokenSource } from "./app.mjs";
 import { login } from "./auth.mjs";
-import { DEFAULT_SERVER, forgetCredentials, readCredentials, writeCredentials } from "./config.mjs";
+import {
+  DEFAULT_SERVER,
+  forgetCredentials,
+  readCredentials,
+  readSettings,
+  writeCredentials,
+  writeSettings,
+} from "./config.mjs";
 import { harbors, myWork, taskLine, taskList, todayLocal } from "./format.mjs";
 import { colourDepth, logoLines } from "./logo.mjs";
 import { HarborError, createClient } from "./mcp.mjs";
+import { jsonText, plain } from "./plain.mjs";
 
 export const HELP = `harbor: Harbor from the terminal
 
@@ -19,6 +27,7 @@ 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 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
@@ -54,21 +63,39 @@ function banner(io, env, words) {
   return `\n${logoLines(depth, words({ bold, dim })).join("\n")}\n`;
 }
 
+const THEMES = ["auto", "light", "dark"];
+
 const COMMON = { flags: ["json", "help"], options: ["harbor"] };
 const spec = (flags = [], options = []) => ({
   flags: [...COMMON.flags, ...flags],
   options: [...COMMON.options, ...options],
 });
 
+/**
+ * How to open a web address on this platform, as a program and its
+ * arguments (never through a shell). Windows' `cmd /c start` would read
+ * each & in the address as the end of a command: the sign-in link has
+ * several. Only http(s) addresses are opened.
+ */
+export function browserCommand(url, platform = process.platform) {
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return null;
+  }
+  if (parsed.protocol !== "https:" && parsed.protocol !== "http:") return null;
+  const href = parsed.toString();
+  if (platform === "darwin") return ["open", [href]];
+  if (platform === "win32") return ["rundll32", ["url.dll,FileProtocolHandler", href]];
+  return ["xdg-open", [href]];
+}
+
 function openBrowser(url) {
-  const [cmd, args] =
-    process.platform === "darwin"
-      ? ["open", [url]]
-      : process.platform === "win32"
-        ? ["cmd", ["/c", "start", "", url]]
-        : ["xdg-open", [url]];
+  const command = browserCommand(url);
+  if (!command) return;
   try {
-    spawn(cmd, args, { stdio: "ignore", detached: true })
+    spawn(command[0], command[1], { stdio: "ignore", detached: true })
       .on("error", () => {})
       .unref();
   } catch {
@@ -167,6 +194,7 @@ export async function run(argv, io = {}) {
       source: tokenSource({ creds, save: (c) => writeCredentials(c, env), fetcher }),
       fetcher,
       harbor: values.harbor,
+      theme: (await readSettings(env)).theme,
     });
     return 0;
   }
@@ -199,6 +227,26 @@ export async function run(argv, io = {}) {
     return 0;
   }
 
+  if (command === "theme") {
+    const { positionals } = parseArgs(rest, { flags: [], options: [] });
+    const settings = await readSettings(env);
+    const [choice] = positionals;
+    if (!choice) {
+      out(`The app's colours: ${settings.theme ?? "auto"}.`);
+      return 0;
+    }
+    if (!THEMES.includes(choice)) {
+      throw new HarborError(`Pick auto, light or dark (not "${choice}").`);
+    }
+    await writeSettings({ ...settings, theme: choice }, env);
+    out(
+      choice === "auto"
+        ? "The app will ask the terminal for its background and match it."
+        : `The app will use its ${choice} colours.`,
+    );
+    return 0;
+  }
+
   if (command === "logout") {
     await forgetCredentials(env);
     out(
@@ -217,7 +265,7 @@ export async function run(argv, io = {}) {
       if (err instanceof HarborError) throw new HarborError(hint(err.message));
       throw err;
     });
-    out(asJson ? JSON.stringify(result, null, 2) : show(result));
+    out(asJson ? jsonText(result) : plain(show(result)));
     return 0;
   };
   let asJson = false;

package/lib/config.mjs

@@ -2,7 +2,7 @@
  * Where the CLI keeps its sign-in: one JSON file per machine, readable only
  * by its owner. HARBOR_CONFIG_DIR moves it (tests, several accounts).
  */
-import { chmod, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { chmod, mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
 
@@ -27,11 +27,30 @@ export async function readCredentials(env = process.env) {
 
 export async function writeCredentials(creds, env = process.env) {
   await mkdir(configDir(env), { recursive: true, mode: 0o700 });
-  await writeFile(file(env), JSON.stringify(creds, null, 2), { mode: 0o600 });
-  // writeFile keeps an existing file's mode; make sure it's private.
-  await chmod(file(env), 0o600);
+  // A fresh private file swapped in whole: the app renews tokens while it
+  // runs, and a write cut short must not leave half a sign-in behind.
+  const temp = `${file(env)}.${process.pid}.tmp`;
+  await writeFile(temp, JSON.stringify(creds, null, 2), { mode: 0o600, flag: "w" });
+  await chmod(temp, 0o600);
+  await rename(temp, file(env));
 }
 
 export async function forgetCredentials(env = process.env) {
   await rm(file(env), { force: true });
 }
+
+const settingsFile = (env) => join(configDir(env), "settings.json");
+
+/** Choices that aren't a sign-in (the app's colours), or {} when none are saved. */
+export async function readSettings(env = process.env) {
+  try {
+    return JSON.parse(await readFile(settingsFile(env), "utf8"));
+  } catch {
+    return {};
+  }
+}
+
+export async function writeSettings(settings, env = process.env) {
+  await mkdir(configDir(env), { recursive: true, mode: 0o700 });
+  await writeFile(settingsFile(env), JSON.stringify(settings, null, 2));
+}

package/lib/logo.mjs

@@ -37,7 +37,7 @@ export const LOGO = [
   "...TTTTTTTTTTTTTTTTTT...",
 ];
 
-/** 16 by 16, for narrow places. */
+/** 16 by 16, for the keys overlay. */
 export const LOGO_SMALL = [
   "..TTTTTTTTTTTT..",
   ".TTTTTTTTTTTTTT.",

package/lib/plain.mjs

@@ -0,0 +1,47 @@
+/**
+ * Text from a harbor, made safe to show in a terminal. A task title can come
+ * from a public intake form, a GitHub pull request or any member, and a
+ * terminal acts on control characters it's sent: an escape sequence in a
+ * title could set the clipboard, retitle the window or hide what's around
+ * it. So they're taken out before anything is printed: the C0 and C1
+ * controls (tab and newline stay), DEL, and the bidirectional overrides that
+ * make text read in a different order than it's stored.
+ */
+// eslint-disable-next-line no-control-regex
+const UNSAFE = /[\u0000-\u0008\u000b-\u001f\u007f-\u009f‪-‮⁦-⁩]/g;
+
+/** @param {string} text */
+export function plain(text) {
+  return text.replace(UNSAFE, "");
+}
+
+/**
+ * Every string in a value made plain: what the full-screen app takes in from
+ * Harbor, before any of it reaches the screen.
+ * @template T
+ * @param {T} value
+ * @returns {T}
+ */
+export function plainDeep(value) {
+  if (typeof value === "string") return /** @type {T} */ (/** @type {unknown} */ (plain(value)));
+  if (Array.isArray(value)) return /** @type {T} */ (/** @type {unknown} */ (value.map(plainDeep)));
+  if (value && typeof value === "object") {
+    /** @type {Record<string, unknown>} */
+    const out = {};
+    for (const [k, v] of Object.entries(value)) out[k] = plainDeep(v);
+    return /** @type {T} */ (/** @type {unknown} */ (out));
+  }
+  return value;
+}
+
+/**
+ * JSON for --json: the data exactly, with the characters a terminal would
+ * act on written as \u escapes (JSON.stringify already does this for C0).
+ * @param {unknown} value
+ */
+export function jsonText(value) {
+  return JSON.stringify(value, null, 2).replace(
+    /[\u007f-\u009f‪-‮⁦-⁩]/g,
+    (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, "0")}`,
+  );
+}

package/lib/update.mjs

@@ -0,0 +1,73 @@
+/**
+ * A line saying when a newer @harborppm/cli is out, since a global npm
+ * install never updates itself. npm is asked at most once a day, while the
+ * command runs (never holding it up more than a moment), and the answer is
+ * kept beside the sign-in. Nothing is said in scripts and CI: only to a
+ * terminal, and never when HARBOR_NO_UPDATE_CHECK or NO_UPDATE_NOTIFIER is set.
+ */
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { configDir } from "./config.mjs";
+
+export const LATEST_URL = "https://registry.npmjs.org/@harborppm/cli/latest";
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+/** Whether version `a` is newer than `b` (plain x.y.z; a pre-release never counts as newer). */
+export function isNewer(a, b) {
+  const parse = (v) => /^(\d+)\.(\d+)\.(\d+)$/.exec(String(v))?.slice(1).map(Number);
+  const x = parse(a);
+  const y = parse(b);
+  if (!x || !y) return false;
+  for (let i = 0; i < 3; i++) if (x[i] !== y[i]) return x[i] > y[i];
+  return false;
+}
+
+/**
+ * The line to show after a command, or null.
+ * @param {{ version: string, env?: Record<string, string | undefined>, stream?: { isTTY?: boolean },
+ *   fetcher?: typeof fetch, now?: () => number, timeoutMs?: number }} opts
+ */
+export async function updateNotice({
+  version,
+  env = process.env,
+  stream = process.stderr,
+  fetcher = fetch,
+  now = Date.now,
+  timeoutMs = 1500,
+}) {
+  if (!stream.isTTY || env.CI || env.HARBOR_NO_UPDATE_CHECK || env.NO_UPDATE_NOTIFIER) return null;
+  const file = join(configDir(env), "update-check.json");
+  let kept = {};
+  try {
+    kept = JSON.parse(await readFile(file, "utf8"));
+  } catch {
+    // Never checked here yet.
+  }
+  let latest = typeof kept.latest === "string" ? kept.latest : null;
+  if (!(Number(kept.checkedAt) > now() - DAY_MS)) {
+    // A plain timer, not AbortSignal.timeout: that one doesn't keep Node
+    // running, so a stalled answer after a quick command would never end.
+    const stop = new AbortController();
+    const timer = setTimeout(() => stop.abort(), timeoutMs);
+    try {
+      const res = await fetcher(LATEST_URL, { signal: stop.signal });
+      if (res.ok) {
+        const body = await res.json();
+        if (typeof body?.version === "string") latest = body.version;
+      }
+    } catch {
+      // Offline or slow: say nothing, and ask again tomorrow.
+    } finally {
+      clearTimeout(timer);
+    }
+    try {
+      await mkdir(configDir(env), { recursive: true, mode: 0o700 });
+      await writeFile(file, JSON.stringify({ checkedAt: now(), latest }));
+    } catch {
+      // Can't keep it: ask again next time.
+    }
+  }
+  return latest && isNewer(latest, version)
+    ? `Harbor CLI ${latest} is out (you have ${version}): npm install -g @harborppm/cli@latest`
+    : null;
+}

package/package.json

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