@harborppm/cli 0.2.0 → 0.4.0

package/README.md

@@ -12,14 +12,30 @@ 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`:
+`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:
 
-- **Today**: what's on you, late first; who's waiting on you; your risks and issues.
-- **Projects**: every portfolio, program and project with its health. Enter opens a project's board (columns side by side) or its list (`v`).
-- **A task**: every field changes in place: title, status, owner, due date (`2026-10-14`, `today`, `+3`), priority, project, notes, checklist steps, comments.
-- **Programs, Risks, People**, and **Harbors** (`6`) to switch between the harbors you belong to.
+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.
+3. **Projects**: every portfolio, program and project with its health. A project opens on its board (columns side by side), its list, or its budget and spend ledger (`v`); `e` changes its details: lead, dates, budget, health by hand with a note.
+4. **Programs**: a program's projects and milestones side by side (`m` adds a milestone, space ticks one), its next move and health.
+5. **Risks**: the register, worst first. Enter changes one (status, owner, likelihood, impact, mitigation); `n` logs a risk, issue or decision.
+6. **People**: open and late work and the next four weeks against each person's capacity; Enter changes their capacity, role, or the time they're promised to a program.
+7. **Roadmap**: a portfolio's programs and projects across the months, in their health's colour, ◆ for milestones.
+8. **History**: who changed what, for a portfolio, program or project (`s` picks which).
 
-Keys: `↑↓` (or `j k`) and `←→` (or `h l`) move, Enter opens, Esc goes back, `/` finds a task by its key or words, `n` adds a task, `[` `]` move a card a column, `x` marks it done, `d` deletes (it asks first), `u` undoes your last change, `?` lists them all.
+A task changes in place too: title, status, owner, due date (`2026-10-14`, `today`, `+3`), priority, project, notes, checklist steps, comments.
+
+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.
+
+`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.
 

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);
   },
 );