@harborppm/cli 0.2.0 → 0.4.0

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

@@ -4,12 +4,15 @@
  * drive it without a terminal.
  */
 import { spawn } from "node:child_process";
+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 { 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
 
@@ -17,6 +20,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 --version                            which version this is
 
   harbor mine                                 what's on you, late first
   harbor tasks [words] [--project P] [--assignee me|NAME] [--late] [--status S]
@@ -38,21 +42,50 @@ export const HELP = `harbor: Harbor from the terminal
   delete; the full-screen app can, as the website can, and asks first.
 `;
 
+export const VERSION = JSON.parse(
+  readFileSync(new URL("../package.json", import.meta.url), "utf8"),
+).version;
+
+/** The mark with a few words beside it, for a terminal that shows colour; nothing otherwise. */
+function banner(io, env, words) {
+  const depth = colourDepth(io.stdout ?? process.stdout, env);
+  if (depth === "none") return null;
+  const bold = (s) => `\x1b[1m${s}\x1b[0m`;
+  const dim = (s) => `\x1b[2m${s}\x1b[0m`;
+  return `\n${logoLines(depth, words({ bold, dim })).join("\n")}\n`;
+}
+
 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 {
@@ -94,7 +127,20 @@ export async function run(argv, io = {}) {
   const [command, ...rest] = argv;
 
   if (command === "help" || command === "--help" || command === "-h") {
-    out(HELP);
+    const top = banner(io, env, ({ bold, dim }) => [
+      bold("Harbor"),
+      "Portfolios, programs and projects,",
+      "from the terminal.",
+      "",
+      dim(`cli ${VERSION} · harborppm.com`),
+    ]);
+    // The banner says what the help's first line does.
+    out(top ? `${top}${HELP.slice(HELP.indexOf("\n"))}` : HELP);
+    return 0;
+  }
+
+  if (command === "--version" || command === "-v" || command === "version") {
+    out(VERSION);
     return 0;
   }
 
@@ -158,7 +204,15 @@ export async function run(argv, io = {}) {
     });
     await writeCredentials(creds, env);
     const canWrite = creds.scope.split(" ").includes("harbor:write");
-    out(`Signed in to ${server}${canWrite ? "." : ", reading only."}`);
+    const said = `Signed in to ${server}${canWrite ? "." : ", reading only."}`;
+    const welcome = banner(io, env, ({ bold, dim }) => [
+      bold("Welcome aboard."),
+      said,
+      "",
+      dim("harbor        the full-screen app"),
+      dim("harbor help   every command"),
+    ]);
+    out(welcome ?? said);
     return 0;
   }
 
@@ -180,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

@@ -0,0 +1,174 @@
+/**
+ * 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. */
+export 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. */
+export 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. */
+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" };
+
+/**
+ * @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[][]}
+ */
+export 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[/** @type {"T"|"W"|"C"} */ (top[x])];
+      const b = LOGO_COLOURS[/** @type {"T"|"W"|"C"} */ (bottom[x])];
+      // A bow is two pixels wide; each half of it fills the inner half of its pixel.
+      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;
+}
+
+/** @param {string} hex */
+const rgb = (hex) => [1, 3, 5].map((i) => parseInt(hex.slice(i, i + 2), 16));
+
+/** The nearest of xterm's 256 colours, for terminals without true colour. */
+/** @param {string} hex */
+export function xterm256(hex) {
+  const steps = [0, 95, 135, 175, 215, 255];
+  const near = (/** @type {number} */ v) =>
+    steps.reduce((best, s, i) => (Math.abs(s - v) < Math.abs(steps[best] - v) ? i : best), 0);
+  const [r, g, b] = rgb(hex).map(near);
+  return 16 + 36 * r + 6 * g + b;
+}
+
+/**
+ * Whether to draw in colour here, and how: none when piped, when NO_COLOR is
+ * set or the terminal is dumb; true colour when the terminal says so.
+ * @param {{ isTTY?: boolean }} stream
+ * @param {Record<string, string | undefined>} env
+ * @returns {"none" | "256" | "truecolor"}
+ */
+export function colourDepth(stream, env) {
+  if (!stream.isTTY || env.NO_COLOR || env.TERM === "dumb") return "none";
+  return /truecolor|24bit/i.test(env.COLORTERM ?? "") ? "truecolor" : "256";
+}
+
+/**
+ * The logo as lines of ANSI text, with words beside it (vertically centred).
+ * @param {"256" | "truecolor"} depth
+ * @param {string[]} [beside]
+ * @param {string[]} [pixels]
+ */
+export function logoLines(depth, beside = [], pixels = LOGO) {
+  /** @param {string} hex @param {38 | 48} layer */
+  const sgr = (hex, layer) =>
+    depth === "truecolor" ? `${layer};2;${rgb(hex).join(";")}` : `${layer};5;${xterm256(hex)}`;
+  const rows = logoRows(pixels).map((runs) =>
+    runs
+      .map((r) => {
+        const codes = [r.fg && sgr(r.fg, 38), r.bg && sgr(r.bg, 48)].filter(Boolean);
+        return codes.length ? `\x1b[${codes.join(";")}m${r.text}\x1b[0m` : r.text;
+      })
+      .join(""),
+  );
+  const from = Math.max(0, Math.floor((rows.length - beside.length) / 2));
+  return rows.map((row, i) => {
+    const words = beside[i - from];
+    return words ? `  ${row}   ${words}` : `  ${row}`;
+  });
+}

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.2.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": {