@harborppm/cli 0.3.0 → 0.4.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, and keeps a small one at the foot of the sidebar when the terminal is tall enough (21 rows or more; the larger one from 110 columns). 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.
@@ -29,6 +29,14 @@ Keys: `↑↓` (or `j k`) and `←→` (or `h l`) move, Enter opens, Esc goes ba
 
 `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

@@ -192,6 +192,137 @@ const createImpl = (createState) => {
 };
 const create$1 = ((createState) => createState ? createImpl(createState) : createImpl);
 
+//#endregion
+//#region cli/lib/logo.mjs
+/**
+* Harbor's mark for the terminal: the favicon (public/favicon.svg) as
+* pixels, a teal tile with the white H and three coral boats. Each
+* terminal row draws two pixel rows with half blocks (▀ ▄ █), so a square
+* grid comes out square. `harbor help` prints it; the full-screen app draws
+* it on its splash and its keys overlay (src/tui/logo.tsx).
+*
+* T teal, W white, C coral, P a boat's pointed bow (coral in the middle of
+* the two pixels, drawn with quarter blocks), . nothing (the rounded corners).
+*/
+/** 24 by 24: posts three wide, a pixel of water between each boat and the posts. */
+const LOGO = [
+	"...TTTTTTTTTTTTTTTTTT...",
+	"..TTTTTTTTTTTTTTTTTTTT..",
+	".TTTTTTTTTTTTTTTTTTTTTT.",
+	"TTTTTWWWTTTTTTTTWWWTTTTT",
+	"TTTTTWWWTTTTTTTTWWWTTTTT",
+	"TTPPTWWWTTTTTTTTWWWTTTTT",
+	"TTCCTWWWTTTTTTTTWWWTTTTT",
+	"TTCCTWWWTTTTTTTTWWWTTTTT",
+	"TTCCTWWWTTTTTTTTWWWTTTTT",
+	"TTCCTWWWTTTTTTTTWWWTTTTT",
+	"TTTTTWWWTTTTTTTTWWWTTTTT",
+	"TTTTTWWWWWWWWWWWWWWTTTTT",
+	"TTTTTWWWWWWWWWWWWWWTTTTT",
+	"TTTTTWWWTTTTTTTTWWWTTTTT",
+	"TTTTTWWWTTTTTTTTWWWTPPTT",
+	"TTTTTWWWTTTPPTTTWWWTCCTT",
+	"TTTTTWWWTTTCCTTTWWWTCCTT",
+	"TTTTTWWWTTTCCTTTWWWTCCTT",
+	"TTTTTWWWTTTCCTTTWWWTCCTT",
+	"TTTTTWWWTTTCCTTTWWWTTTTT",
+	"TTTTTWWWTTTTTTTTWWWTTTTT",
+	".TTTTTTTTTTTTTTTTTTTTTT.",
+	"..TTTTTTTTTTTTTTTTTTTT..",
+	"...TTTTTTTTTTTTTTTTTT..."
+];
+/** 16 by 16, for narrow places. */
+const LOGO_SMALL = [
+	"..TTTTTTTTTTTT..",
+	".TTTTTTTTTTTTTT.",
+	"TTTTWWTTTTWWTTTT",
+	"TTTTWWTTTTWWTTTT",
+	"TPPTWWTTTTWWTTTT",
+	"TCCTWWTTTTWWTTTT",
+	"TCCTWWTTTTWWTTTT",
+	"TTTTWWWWWWWWTTTT",
+	"TTTTWWWWWWWWTTTT",
+	"TTTTWWTTTTWWTPPT",
+	"TTTTWWTPPTWWTCCT",
+	"TTTTWWTCCTWWTCCT",
+	"TTTTWWTCCTWWTTTT",
+	"TTTTWWTTTTWWTTTT",
+	".TTTTTTTTTTTTTT.",
+	"..TTTTTTTTTTTT.."
+];
+/** 12 by 12, for the full-screen app's sidebar: posts and side boats a pixel wide, no bows. */
+const LOGO_MINI = [
+	"..TTTTTTTT..",
+	".TTTTTTTTTT.",
+	"TTTWTTTTWTTT",
+	"TCTWTTTTWTTT",
+	"TCTWTTTTWTTT",
+	"TCTWWWWWWTTT",
+	"TTTWWWWWWTTT",
+	"TTTWTTTTWTCT",
+	"TTTWTCCTWTCT",
+	"TTTWTCCTWTCT",
+	".TTTTTTTTTT.",
+	"..TTTTTTTT.."
+];
+/** The brand's fills, as in favicon.svg and src/styles.css. */
+const LOGO_COLOURS = {
+	T: "#0f6e64",
+	W: "#ffffff",
+	C: "#c44a2c"
+};
+/**
+* @typedef {{ text: string, fg?: string, bg?: string }} Run
+* One stretch of a terminal row in the same colours.
+*/
+/**
+* The logo as terminal rows, each a list of runs: the top pixel is the
+* half block's colour, the bottom one its background.
+* @param {string[]} pixels
+* @returns {Run[][]}
+*/
+function logoRows(pixels = LOGO) {
+	/** @type {Run[][]} */
+	const rows = [];
+	for (let y = 0; y < pixels.length; y += 2) {
+		/** @type {Run[]} */
+		const runs = [];
+		const top = pixels[y] ?? "";
+		const bottom = pixels[y + 1] ?? "";
+		for (let x = 0; x < top.length; x++) {
+			const t = LOGO_COLOURS[top[x]];
+			const b = LOGO_COLOURS[bottom[x]];
+			const bowRow = top[x] === "P" ? top : bottom[x] === "P" ? bottom : null;
+			const left = bowRow ? bowRow[x - 1] !== "P" : false;
+			/** @type {Run} */
+			const cell = top[x] === "P" ? {
+				text: left ? "▟" : "▙",
+				fg: LOGO_COLOURS.C,
+				bg: LOGO_COLOURS.T
+			} : bottom[x] === "P" ? {
+				text: left ? "▗" : "▖",
+				fg: LOGO_COLOURS.C,
+				bg: t
+			} : !t && !b ? { text: " " } : t === b || !b ? {
+				text: t === b ? "█" : "▀",
+				fg: t
+			} : !t ? {
+				text: "▄",
+				fg: b
+			} : {
+				text: "▀",
+				fg: t,
+				bg: b
+			};
+			const last = runs.at(-1);
+			if (last && last.fg === cell.fg && last.bg === cell.bg) last.text += cell.text;
+			else runs.push(cell);
+		}
+		rows.push(runs);
+	}
+	return rows;
+}
+
 //#endregion
 //#region src/tui/context.tsx
 /**
@@ -210,6 +341,71 @@ function useHarbor(selector) {
 	return useStore(useDeps().store, selector);
 }
 
+//#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"
+};
+const PRIORITY_COLOR = {
+	urgent: "red",
+	high: "#e0714f",
+	medium: void 0,
+	low: "gray"
+};
+
+//#endregion
+//#region src/tui/logo.tsx
+/** Harbor's mark in half blocks (cli/lib/logo.mjs holds the pixels). */
+function Logo({ pixels = LOGO }) {
+	return /* @__PURE__ */ jsx(Box, {
+		flexDirection: "column",
+		flexShrink: 0,
+		children: logoRows(pixels).map((runs, y) => /* @__PURE__ */ jsx(Text, { children: runs.map((r, i) => /* @__PURE__ */ jsx(Text, {
+			color: r.fg,
+			backgroundColor: r.bg,
+			children: r.text
+		}, i)) }, y))
+	});
+}
+/** What shows while the harbor loads: the mark, centred, and which harbor. */
+function Splash({ opening }) {
+	const { columns, rows } = useWindowSize();
+	const mark = rows >= 18 && columns >= 30;
+	const height = (mark ? LOGO.length / 2 + 1 : 0) + 2;
+	return /* @__PURE__ */ jsxs(Box, {
+		width: columns,
+		height: rows,
+		flexDirection: "column",
+		alignItems: "center",
+		paddingTop: Math.max(0, Math.floor((rows - height) / 2)),
+		children: [
+			mark ? /* @__PURE__ */ jsx(Box, {
+				marginBottom: 1,
+				children: /* @__PURE__ */ jsx(Logo, {})
+			}) : null,
+			/* @__PURE__ */ jsx(Text, {
+				bold: true,
+				color: theme.accent,
+				children: "Harbor"
+			}),
+			/* @__PURE__ */ jsx(Text, {
+				color: theme.muted,
+				children: opening ? `Opening ${opening}…` : "Opening your harbor…"
+			})
+		]
+	});
+}
+
 //#endregion
 //#region node_modules/date-fns/constants.js
 /**
@@ -2075,28 +2271,6 @@ function forecastLine(f) {
 	return `At this rate it ends at ${money(Math.round(f.eac))} (${money(gap)} ${side} budget)`;
 }
 
-//#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"
-};
-const PRIORITY_COLOR = {
-	urgent: "red",
-	high: "#e0714f",
-	medium: void 0,
-	low: "gray"
-};
-
 //#endregion
 //#region src/tui/ui.tsx
 /**
@@ -3457,165 +3631,6 @@ function PeopleView({ active, width, height, go }) {
 	});
 }
 
-//#endregion
-//#region cli/lib/logo.mjs
-/**
-* Harbor's mark for the terminal: the favicon (public/favicon.svg) as
-* pixels, a teal tile with the white H and three coral boats. Each
-* terminal row draws two pixel rows with half blocks (▀ ▄ █), so a square
-* grid comes out square. `harbor help` prints it; the full-screen app draws
-* it on its splash and its keys overlay (src/tui/logo.tsx).
-*
-* T teal, W white, C coral, P a boat's pointed bow (coral in the middle of
-* the two pixels, drawn with quarter blocks), . nothing (the rounded corners).
-*/
-/** 24 by 24: posts three wide, a pixel of water between each boat and the posts. */
-const LOGO = [
-	"...TTTTTTTTTTTTTTTTTT...",
-	"..TTTTTTTTTTTTTTTTTTTT..",
-	".TTTTTTTTTTTTTTTTTTTTTT.",
-	"TTTTTWWWTTTTTTTTWWWTTTTT",
-	"TTTTTWWWTTTTTTTTWWWTTTTT",
-	"TTPPTWWWTTTTTTTTWWWTTTTT",
-	"TTCCTWWWTTTTTTTTWWWTTTTT",
-	"TTCCTWWWTTTTTTTTWWWTTTTT",
-	"TTCCTWWWTTTTTTTTWWWTTTTT",
-	"TTCCTWWWTTTTTTTTWWWTTTTT",
-	"TTTTTWWWTTTTTTTTWWWTTTTT",
-	"TTTTTWWWWWWWWWWWWWWTTTTT",
-	"TTTTTWWWWWWWWWWWWWWTTTTT",
-	"TTTTTWWWTTTTTTTTWWWTTTTT",
-	"TTTTTWWWTTTTTTTTWWWTPPTT",
-	"TTTTTWWWTTTPPTTTWWWTCCTT",
-	"TTTTTWWWTTTCCTTTWWWTCCTT",
-	"TTTTTWWWTTTCCTTTWWWTCCTT",
-	"TTTTTWWWTTTCCTTTWWWTCCTT",
-	"TTTTTWWWTTTCCTTTWWWTTTTT",
-	"TTTTTWWWTTTTTTTTWWWTTTTT",
-	".TTTTTTTTTTTTTTTTTTTTTT.",
-	"..TTTTTTTTTTTTTTTTTTTT..",
-	"...TTTTTTTTTTTTTTTTTT..."
-];
-/** 16 by 16, for narrow places. */
-const LOGO_SMALL = [
-	"..TTTTTTTTTTTT..",
-	".TTTTTTTTTTTTTT.",
-	"TTTTWWTTTTWWTTTT",
-	"TTTTWWTTTTWWTTTT",
-	"TPPTWWTTTTWWTTTT",
-	"TCCTWWTTTTWWTTTT",
-	"TCCTWWTTTTWWTTTT",
-	"TTTTWWWWWWWWTTTT",
-	"TTTTWWWWWWWWTTTT",
-	"TTTTWWTTTTWWTPPT",
-	"TTTTWWTPPTWWTCCT",
-	"TTTTWWTCCTWWTCCT",
-	"TTTTWWTCCTWWTTTT",
-	"TTTTWWTTTTWWTTTT",
-	".TTTTTTTTTTTTTT.",
-	"..TTTTTTTTTTTT.."
-];
-/** The brand's fills, as in favicon.svg and src/styles.css. */
-const LOGO_COLOURS = {
-	T: "#0f6e64",
-	W: "#ffffff",
-	C: "#c44a2c"
-};
-/**
-* @typedef {{ text: string, fg?: string, bg?: string }} Run
-* One stretch of a terminal row in the same colours.
-*/
-/**
-* The logo as terminal rows, each a list of runs: the top pixel is the
-* half block's colour, the bottom one its background.
-* @param {string[]} pixels
-* @returns {Run[][]}
-*/
-function logoRows(pixels = LOGO) {
-	/** @type {Run[][]} */
-	const rows = [];
-	for (let y = 0; y < pixels.length; y += 2) {
-		/** @type {Run[]} */
-		const runs = [];
-		const top = pixels[y] ?? "";
-		const bottom = pixels[y + 1] ?? "";
-		for (let x = 0; x < top.length; x++) {
-			const t = LOGO_COLOURS[top[x]];
-			const b = LOGO_COLOURS[bottom[x]];
-			const bowRow = top[x] === "P" ? top : bottom[x] === "P" ? bottom : null;
-			const left = bowRow ? bowRow[x - 1] !== "P" : false;
-			/** @type {Run} */
-			const cell = top[x] === "P" ? {
-				text: left ? "▟" : "▙",
-				fg: LOGO_COLOURS.C,
-				bg: LOGO_COLOURS.T
-			} : bottom[x] === "P" ? {
-				text: left ? "▗" : "▖",
-				fg: LOGO_COLOURS.C,
-				bg: t
-			} : !t && !b ? { text: " " } : t === b || !b ? {
-				text: t === b ? "█" : "▀",
-				fg: t
-			} : !t ? {
-				text: "▄",
-				fg: b
-			} : {
-				text: "▀",
-				fg: t,
-				bg: b
-			};
-			const last = runs.at(-1);
-			if (last && last.fg === cell.fg && last.bg === cell.bg) last.text += cell.text;
-			else runs.push(cell);
-		}
-		rows.push(runs);
-	}
-	return rows;
-}
-
-//#endregion
-//#region src/tui/logo.tsx
-/** Harbor's mark in half blocks (cli/lib/logo.mjs holds the pixels). */
-function Logo({ pixels = LOGO }) {
-	return /* @__PURE__ */ jsx(Box, {
-		flexDirection: "column",
-		flexShrink: 0,
-		children: logoRows(pixels).map((runs, y) => /* @__PURE__ */ jsx(Text, { children: runs.map((r, i) => /* @__PURE__ */ jsx(Text, {
-			color: r.fg,
-			backgroundColor: r.bg,
-			children: r.text
-		}, i)) }, y))
-	});
-}
-/** What shows while the harbor loads: the mark, centred, and which harbor. */
-function Splash({ opening }) {
-	const { columns, rows } = useWindowSize();
-	const mark = rows >= 18 && columns >= 30;
-	const height = (mark ? LOGO.length / 2 + 1 : 0) + 2;
-	return /* @__PURE__ */ jsxs(Box, {
-		width: columns,
-		height: rows,
-		flexDirection: "column",
-		alignItems: "center",
-		paddingTop: Math.max(0, Math.floor((rows - height) / 2)),
-		children: [
-			mark ? /* @__PURE__ */ jsx(Box, {
-				marginBottom: 1,
-				children: /* @__PURE__ */ jsx(Logo, {})
-			}) : null,
-			/* @__PURE__ */ jsx(Text, {
-				bold: true,
-				color: theme.accent,
-				children: "Harbor"
-			}),
-			/* @__PURE__ */ jsx(Text, {
-				color: theme.muted,
-				children: opening ? `Opening ${opening}…` : "Opening your harbor…"
-			})
-		]
-	});
-}
-
 //#endregion
 //#region src/tui/moves.ts
 /**
@@ -5811,6 +5826,8 @@ const NAV = [
 		label: "History"
 	}
 ];
+/** The sidebar's lines: the screens, a gap, then Harbors and Anything. */
+const NAV_LINES = NAV.length + 3;
 const SAVE_LABEL = {
 	saved: ["● saved", "green"],
 	pending: ["● saving soon", "yellow"],
@@ -6004,7 +6021,8 @@ 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 mark = columns >= 110 && bodyHeight >= NAV_LINES + 1 + LOGO_SMALL.length / 2 ? LOGO_SMALL : bodyHeight >= NAV_LINES + 1 + LOGO_MINI.length / 2 ? LOGO_MINI : null;
+	const navWidth = (mark?.[0]?.length ?? LOGO_MINI.length) + 3;
 	const mainWidth = Math.max(30, columns - navWidth - 1);
 	const mainActive = focus === "main" && !covered && panel === null;
 	const [saveText, saveColor] = SAVE_LABEL[save];
@@ -6282,7 +6300,8 @@ function App({ ui }) {
 						/* @__PURE__ */ jsx(Text, {
 							color: theme.muted,
 							children: ": Anything"
-						})
+						}),
+						mark ? /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsx(Box, { flexGrow: 1 }), /* @__PURE__ */ jsx(Logo, { pixels: mark })] }) : null
 					]
 				}), /* @__PURE__ */ jsxs(Box, {
 					flexDirection: "column",
@@ -8560,8 +8579,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;
@@ -8844,30 +8917,35 @@ 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 = {}) {
+	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 +8954,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 })
@@ -8902,10 +8980,11 @@ async function runApp(opts) {
 		transport,
 		account,
 		harbors,
-		workspaceId: pick?.id
+		workspaceId: pick?.id,
+		splashMs: SPLASH_MS
 	}, { 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

@@ -12,6 +12,7 @@ import { DEFAULT_SERVER, forgetCredentials, readCredentials, writeCredentials }
 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
 
@@ -60,15 +61,31 @@ const spec = (flags = [], options = []) => ({
   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 {
@@ -217,7 +234,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,9 +27,12 @@ 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) {

package/lib/logo.mjs

@@ -57,6 +57,22 @@ export const LOGO_SMALL = [
   "..TTTTTTTTTTTT..",
 ];
 
+/** 12 by 12, for the full-screen app's sidebar: posts and side boats a pixel wide, no bows. */
+export const LOGO_MINI = [
+  "..TTTTTTTT..",
+  ".TTTTTTTTTT.",
+  "TTTWTTTTWTTT",
+  "TCTWTTTTWTTT",
+  "TCTWTTTTWTTT",
+  "TCTWWWWWWTTT",
+  "TTTWWWWWWTTT",
+  "TTTWTTTTWTCT",
+  "TTTWTCCTWTCT",
+  "TTTWTCCTWTCT",
+  ".TTTTTTTTTT.",
+  "..TTTTTTTT..",
+];
+
 /** The brand's fills, as in favicon.svg and src/styles.css. */
 export const LOGO_COLOURS = { T: "#0f6e64", W: "#ffffff", C: "#c44a2c" };
 

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.4.0",
   "description": "Harbor from the terminal: a full-screen app with everything, plus commands for scripts and agents.",
   "type": "module",
   "bin": {