@harborppm/cli 0.1.1 → 0.3.0

package/lib/app.mjs

@@ -0,0 +1,41 @@
+/**
+ * `harbor` on its own: the full-screen app (src/tui, bundled into
+ * dist/app.mjs by build.mjs). It needs full access, which `harbor login`
+ * asks for; an older sign-in without it is asked again first.
+ */
+import { refresh } from "./auth.mjs";
+import { HarborError } from "./mcp.mjs";
+
+export const APP_SCOPE = "harbor:app";
+const SKEW_MS = 60_000;
+
+export const hasFullAccess = (creds) => Boolean(creds?.scope?.split(" ").includes(APP_SCOPE));
+
+/** 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);
+  };
+  return {
+    server: current.server,
+    async token() {
+      if (current.expiresAt - SKEW_MS < now()) await renew();
+      return current.accessToken;
+    },
+    renew,
+  };
+}
+
+/** Load the bundled app; a checkout that hasn't built it says how. */
+export async function loadApp() {
+  try {
+    return await import("../dist/app.mjs");
+  } catch (error) {
+    if (error?.code === "ERR_MODULE_NOT_FOUND" && /dist\/app\.mjs/.test(error.message)) {
+      throw new HarborError("The full-screen app isn't built here. Run: node cli/build.mjs");
+    }
+    throw error;
+  }
+}

package/lib/auth.mjs

@@ -8,6 +8,8 @@ import { createServer } from "node:http";
 
 export const CLIENT_NAME = "Harbor CLI";
 export const WRITE_SCOPE = "harbor:write";
+/** Full access, as on the website: what the full-screen app needs (/api/app). */
+export const APP_SCOPE = "harbor:app";
 
 const b64url = (buf) => Buffer.from(buf).toString("base64url");
 
@@ -118,7 +120,9 @@ 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}`,
+    scope: readOnly
+      ? "openid offline_access"
+      : `openid offline_access ${WRITE_SCOPE} ${APP_SCOPE}`,
   }).toString();
   await open(authorize.toString());
 

package/lib/cli.mjs

@@ -4,17 +4,22 @@
  * 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";
 
 export const HELP = `harbor: Harbor from the terminal
 
+  harbor                                      the full-screen app: everything, with the keyboard
   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]
@@ -32,9 +37,23 @@ export const HELP = `harbor: Harbor from the terminal
 
   Every command takes --harbor NAME (when you're in more than one) and --json.
   Statuses: backlog, todo, doing, review, done.
-  Changes show in Harbor's History as yours, "via Harbor CLI". Nothing here deletes.
+  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.
 `;
 
+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],
@@ -90,8 +109,65 @@ export async function run(argv, io = {}) {
   const fetcher = io.fetch ?? fetch;
   const [command, ...rest] = argv;
 
-  if (!command || command === "help" || command === "--help" || command === "-h") {
-    out(HELP);
+  if (command === "help" || command === "--help" || command === "-h") {
+    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;
+  }
+
+  // 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);
+    if (!command && !terminal) {
+      out(HELP);
+      return 0;
+    }
+    if (!terminal) throw new HarborError("The full-screen app needs a terminal.");
+    const { values } = parseArgs(rest, { flags: [], options: ["harbor", "server"] });
+    let creds = await readCredentials(env);
+    if (!hasFullAccess(creds)) {
+      out(
+        creds
+          ? "The full-screen app needs full access, as on the website. Signing in again…"
+          : "Signing in first…",
+      );
+      const code = await run(
+        [
+          "login",
+          ...(values.server
+            ? ["--server", values.server]
+            : creds
+              ? ["--server", creds.server]
+              : []),
+        ],
+        io,
+      );
+      if (code !== 0) return code;
+      creds = await readCredentials(env);
+      if (!hasFullAccess(creds)) {
+        throw new HarborError(
+          "That sign-in allowed reading only, so the app can't open. The commands still work.",
+        );
+      }
+    }
+    const { runApp } = await loadApp();
+    await runApp({
+      source: tokenSource({ creds, save: (c) => writeCredentials(c, env), fetcher }),
+      fetcher,
+      harbor: values.harbor,
+    });
     return 0;
   }
 
@@ -111,7 +187,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;
   }
 

package/lib/logo.mjs

@@ -0,0 +1,158 @@
+/**
+ * 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..",
+];
+
+/** 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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@harborppm/cli",
-  "version": "0.1.1",
-  "description": "Harbor from the terminal: what's on you, add and finish tasks, comment, check in, log risks.",
+  "version": "0.3.0",
+  "description": "Harbor from the terminal: a full-screen app with everything, plus commands for scripts and agents.",
   "type": "module",
   "bin": {
     "harbor": "bin/harbor.mjs"
@@ -9,15 +9,21 @@
   "files": [
     "bin",
     "lib",
+    "dist",
     "README.md",
     "LICENSE"
   ],
   "engines": {
-    "node": ">=20"
+    "node": ">=22"
   },
   "scripts": {
-    "test": "node --test test/*.test.mjs"
+    "test": "node --test test/*.test.mjs",
+    "build": "node build.mjs"
   },
   "homepage": "https://harborppm.com/ai",
-  "license": "MIT"
+  "license": "MIT",
+  "dependencies": {
+    "ink": "^7.1.1",
+    "react": "^19.2.0"
+  }
 }