@harborppm/cli 0.13.0 → 0.14.0

package/README.md

@@ -59,6 +59,16 @@ Your harbor is the same one at [harborppm.com](https://harborppm.com/today?utm_s
 
 The website has the commands too: turn on **Command line at the bottom** in your menu, press `/`, and type `mine`, `add "Call the mill" #ridge @sam --due fri` or `done RR-12`.
 
+## In your shell prompt
+
+`harbor prompt` prints a few characters for your prompt: `⚓ 2 today · 1 late`, with late work in coral, and nothing at all when you're clear. It never waits on the network: it shows the counts it kept and fetches new ones in the background when they're more than five minutes old, or after you change a task. `harbor prompt --init zsh` (or `bash`, `fish`, `starship`) prints the lines to add to your shell's setup:
+
+```zsh
+# ~/.zshrc
+setopt prompt_subst
+RPROMPT='$(harbor prompt --shell zsh)'
+```
+
 ## 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.

package/bin/harbor.mjs

@@ -6,9 +6,11 @@ import { updateNotice } from "../lib/update.mjs";
 
 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);
+// Not for the shell prompt, which draws on every Enter and must never wait.
+const notice =
+  argv.includes("--json") || argv[0] === "prompt"
+    ? Promise.resolve(null)
+    : updateNotice({ version: VERSION }).catch(() => null);
 const tell = async () => {
   const line = await notice;
   if (line) process.stderr.write(`\n${line}\n`);

package/lib/cli.mjs

@@ -29,6 +29,18 @@ import {
 import { colourDepth, logoLines } from "./logo.mjs";
 import { HarborError, createClient } from "./mcp.mjs";
 import { jsonText, plain } from "./plain.mjs";
+import {
+  FETCH_LIMIT,
+  SHELLS,
+  initSnippet,
+  isFresh,
+  promptCounts,
+  readPromptCache,
+  refreshInBackground,
+  segment,
+  stalePromptCache,
+  writePromptCache,
+} from "./prompt.mjs";
 
 export const HELP = `harbor: Harbor from the terminal
 
@@ -50,6 +62,10 @@ export const HELP = `harbor: Harbor from the terminal
   harbor show TASK                            one task (TASK: a key like RR-42)
   harbor open [TASK|PROJECT]                  open it on the website (or Today)
   harbor invite EMAIL [--viewer]              invite someone to your harbor
+  harbor prompt [--shell SHELL] [--refresh]   due today and late, for your
+                                              shell prompt (never waits)
+  harbor prompt --init SHELL                  how to add it: zsh, bash, fish
+                                              or starship
 
   harbor program "NAME" [--portfolio P] [--lead me|NAME] [--starts DATE]
                        [--ends DATE]
@@ -497,6 +513,59 @@ export async function run(argv, io = {}) {
     return 0;
   }
 
+  if (command === "prompt") {
+    const { values, positionals } = parseArgs(rest, {
+      flags: ["refresh", "json"],
+      options: ["shell", "init", "harbor"],
+    });
+    none(positionals);
+    if (values.init !== undefined) {
+      const snippet = initSnippet(values.init);
+      if (!snippet) throw new HarborError(`Pick ${SHELLS.join(", ")} (not "${values.init}").`);
+      out(
+        `${snippet}\n\nYour prompt shows what's due today and late once Harbor has answered,\na moment after the next prompt. harbor prompt --refresh checks now.`,
+      );
+      return 0;
+    }
+    const shell = values.shell;
+    if (shell !== undefined && !SHELLS.includes(shell))
+      throw new HarborError(`--shell is ${SHELLS.join(", ")} (not "${shell}").`);
+    const creds = await readCredentials(env);
+    const harbor = values.harbor ?? creds?.harbor ?? null;
+    const today = todayLocal(io.now ? new Date(io.now()) : new Date());
+    const show = (counts, at) =>
+      out(
+        values.json
+          ? jsonText({ ...(counts ?? { today: null, late: null }), at })
+          : segment(counts ?? {}, shell),
+      );
+    if (!creds) {
+      if (values.refresh) throw new HarborError("Not signed in. Run harbor login.");
+      show(null, null);
+      return 0;
+    }
+    if (values.refresh) {
+      const client = createClient({ creds, save: (c) => writeCredentials(c, env), fetcher });
+      const work = await client.call("my_work", {
+        harbor: harbor ?? undefined,
+        limit: FETCH_LIMIT,
+      });
+      const counts = promptCounts(work, today);
+      const at = io.now?.() ?? Date.now();
+      await writePromptCache({ at, day: today, harbor, counts }, env);
+      show(counts, at);
+      return 0;
+    }
+    // The prompt itself: what's kept, at once, and fresh counts fetched for next time.
+    const cache = await readPromptCache(env);
+    const now = io.now?.() ?? Date.now();
+    if (!isFresh(cache, { now, today, harbor }))
+      await (io.refreshPrompt ?? refreshInBackground)(env, now);
+    const usable = cache && cache.day === today && (cache.harbor ?? null) === harbor;
+    show(usable ? cache.counts : null, usable ? cache.at : null);
+    return 0;
+  }
+
   // A mistyped command says so, signed in or not.
   if (commandHelp(command) === null) {
     throw new HarborError(`No command "${command}". Run harbor help.`);
@@ -516,6 +585,8 @@ export async function run(argv, io = {}) {
       if (err instanceof HarborError) throw new HarborError(hint(err.message));
       throw err;
     });
+    // The prompt's counts are behind now; its next draw fetches new ones.
+    if (name === "create_task" || name === "update_task") await stalePromptCache(env);
     out(asJson ? jsonText(result) : plain(show(result)));
     return 0;
   };

package/lib/prompt.mjs

@@ -0,0 +1,140 @@
+/**
+ * `harbor prompt`: a few characters for a shell prompt saying what's due
+ * today and what's late. A prompt draws on every Enter, so this never waits
+ * on the network and never prints an error: it reads counts kept beside the
+ * sign-in, and when they're older than a few minutes it starts
+ * `harbor prompt --refresh` in the background to fetch new ones for the next
+ * prompt. With nothing due and nothing late it prints nothing.
+ */
+import { spawn } from "node:child_process";
+import { mkdir, readFile, rename, stat, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { configDir } from "./config.mjs";
+
+export const FRESH_MS = 5 * 60 * 1000;
+/** A refresh started this recently is still running (or failed): don't start another. */
+const TRYING_MS = 60 * 1000;
+export const SHELLS = ["zsh", "bash", "fish", "starship"];
+/** As many tasks as my_work gives; late and due-today ones come first, so they fit. */
+export const FETCH_LIMIT = 50;
+
+const cacheFile = (env) => join(configDir(env), "prompt.json");
+const tryingFile = (env) => join(configDir(env), "prompt.trying");
+
+/** Due today and late among your open tasks, by this machine's date. */
+export function promptCounts(work, today) {
+  const tasks = work?.tasks ?? [];
+  return {
+    today: tasks.filter((t) => t.due === today).length,
+    late: tasks.filter((t) => t.due && t.due < today).length,
+  };
+}
+
+// 256-colour codes near Harbor's teal, amber and coral.
+const COLOUR = { mark: 30, today: 179, late: 167 };
+
+/**
+ * The segment as `shell` wants it: zsh and bash need colour codes marked as
+ * taking no room, or the cursor lands in the wrong place; fish takes them
+ * as they are; Starship colours its own modules, so it gets plain text, as
+ * does no shell at all.
+ */
+export function segment({ today, late }, shell) {
+  if (!today && !late) return "";
+  const parts = [];
+  if (today) parts.push(["today", `${today} today`]);
+  if (late) parts.push(["late", `${late} late`]);
+  if (!shell || shell === "starship") return `⚓ ${parts.map(([, s]) => s).join(" · ")}`;
+  const hide =
+    shell === "zsh" ? (s) => `%{${s}%}` : shell === "bash" ? (s) => `\x01${s}\x02` : (s) => s;
+  const paint = (kind, s) => `${hide(`\x1b[38;5;${COLOUR[kind]}m`)}${s}${hide("\x1b[0m")}`;
+  return [paint("mark", "⚓"), ...parts.map(([kind, s]) => paint(kind, s))].join(" ");
+}
+
+/** What to put in the shell's startup file. */
+export function initSnippet(shell) {
+  switch (shell) {
+    case "zsh":
+      return [
+        "# Add to ~/.zshrc",
+        "setopt prompt_subst",
+        "RPROMPT='$(harbor prompt --shell zsh)'",
+      ].join("\n");
+    case "bash":
+      return ["# Add to ~/.bashrc", "PS1='$(harbor prompt --shell bash) '\"$PS1\""].join("\n");
+    case "fish":
+      return [
+        "# Add to ~/.config/fish/config.fish",
+        "function fish_right_prompt",
+        "    harbor prompt --shell fish",
+        "end",
+      ].join("\n");
+    case "starship":
+      return [
+        "# Add to ~/.config/starship.toml",
+        "[custom.harbor]",
+        'command = "harbor prompt --shell starship"',
+        'when = "true"',
+        'style = "bold #c44a2c"',
+        'format = "[$output]($style) "',
+      ].join("\n");
+    default:
+      return null;
+  }
+}
+
+/** The kept counts, or null when there are none. */
+export async function readPromptCache(env = process.env) {
+  try {
+    const c = JSON.parse(await readFile(cacheFile(env), "utf8"));
+    return typeof c?.at === "number" && c.counts ? c : null;
+  } catch {
+    return null;
+  }
+}
+
+export async function writePromptCache(cache, env = process.env) {
+  await mkdir(configDir(env), { recursive: true, mode: 0o700 });
+  const temp = `${cacheFile(env)}.${process.pid}.tmp`;
+  await writeFile(temp, JSON.stringify(cache));
+  await rename(temp, cacheFile(env));
+}
+
+/**
+ * Counts saved for one harbor and one day only: a new day, or `harbor use`
+ * another harbor, makes them stale even if they were fetched a minute ago.
+ */
+export function isFresh(cache, { now, today, harbor }) {
+  return Boolean(
+    cache &&
+    now - cache.at < FRESH_MS &&
+    cache.day === today &&
+    (cache.harbor ?? null) === (harbor ?? null),
+  );
+}
+
+/** Marks the kept counts stale, after a command changed tasks. */
+export async function stalePromptCache(env = process.env) {
+  const cache = await readPromptCache(env);
+  if (cache) await writePromptCache({ ...cache, at: 0 }, env).catch(() => {});
+}
+
+/** Starts `harbor prompt --refresh` on its own, unless one started a moment ago. */
+export async function refreshInBackground(env = process.env, now = Date.now()) {
+  try {
+    const tried = await stat(tryingFile(env)).catch(() => null);
+    if (tried && now - tried.mtimeMs < TRYING_MS) return false;
+    await mkdir(configDir(env), { recursive: true, mode: 0o700 });
+    await writeFile(tryingFile(env), "");
+    const bin = fileURLToPath(new URL("../bin/harbor.mjs", import.meta.url));
+    spawn(process.execPath, [bin, "prompt", "--refresh"], {
+      stdio: "ignore",
+      detached: true,
+      env: { ...env, HARBOR_NO_UPDATE_CHECK: "1" },
+    }).unref();
+    return true;
+  } catch {
+    return false;
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@harborppm/cli",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Harbor from the terminal: a full-screen app with everything, plus commands for scripts and agents.",
   "keywords": [
     "harbor",