@harborppm/cli 0.9.3 → 0.10.1

package/README.md

@@ -12,7 +12,7 @@ Needs Node 22 or later.
 
 ## New to Harbor?
 
-You can start from the terminal. Harbor is free to start.
+You can start from the terminal. A harbor of your own is free for 30 days, no card; after that it's $49 a month for the whole crew, not per seat.
 
 ```sh
 npm install -g @harborppm/cli
@@ -39,10 +39,24 @@ A task changes in place too: title, status, owner, due date (`2026-10-14`, `toda
 
 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.
 
+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.
+
 It has colours for dark terminals and for light ones, and picks by asking the terminal for its background (or reading `COLORFGBG`); a terminal that doesn't say gets the dark ones. `harbor theme light` or `harbor theme dark` settles it, `harbor theme auto` goes back to asking, and `HARBOR_THEME` overrides it for one run.
 
 `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.
 
+## On the website
+
+Your harbor is the same one at [harborppm.com](https://harborppm.com/today?utm_source=npm&utm_medium=readme&utm_campaign=cli), signed in with the same account, so the people you work with don't need a terminal. The website adds what a team shares:
+
+- **Your crew**: invite people by email under **People**; they see the same boards, risks and roadmap, and their changes reach your terminal within seconds.
+- **Status for others**: the weekly brief, a one-click status report, and read-only links for stakeholders.
+- **Intake forms**: a public form that drops requests onto a project's board.
+- **GitHub**: a pull request that names a task's key (RR-42) shows on the task and moves it along.
+- **Claude and other AI apps**, connected over MCP from [harborppm.com/ai](https://harborppm.com/ai?utm_source=npm&utm_medium=readme&utm_campaign=cli).
+
+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`.
+
 ## 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.
@@ -51,8 +65,6 @@ npm doesn't update a global install by itself, so once a day `harbor` asks npm w
 
 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
 
 `harbor signup` is for a first visit: the same sign-in, with the page opened on making an account. `harbor login` registers the CLI with Harbor and opens the same page Claude and other apps use: it names "Harbor CLI" and asks what to allow. Choose **Allow reading only** (or run `harbor login --read-only`) if it shouldn't change anything. The sign-in is saved in `~/.config/harbor/credentials.json`, readable only by you, and refreshes itself for 30 days.
@@ -64,10 +76,16 @@ It runs on the same engine as the website: health, task keys, limits and undo wo
 ```
 harbor harbors                              the harbors you belong to
 harbor use HARBOR|none                      the harbor to work in when you're in several
+harbor programs                             programs and their projects
+harbor projects [words] [--program P]       projects with health and open work
 harbor mine                                 what's on you, late first
 harbor tasks [words] [--project P] [--assignee me|none|NAME] [--late] [--status S,S]
 harbor show TASK                            one task in full
 
+harbor program "NAME" [--portfolio P] [--lead me|NAME] [--starts DATE]
+                     [--ends DATE]
+harbor project "NAME" --program P [--lead me|NAME] [--starts DATE]
+                     [--ends DATE] [--budget N]
 harbor add "TITLE" --project P [--assignee me|NAME] [--due DATE]
                    [--priority low|medium|high|urgent] [--status S] [--over-limit]
 harbor start TASK | review TASK | done TASK [--confirm] [--over-limit]
@@ -81,7 +99,7 @@ harbor issue "TITLE" --project P|--program P [--impact 1-5] [--owner NAME]
                     [--due DATE]
 ```
 
-Every command takes `--json` for the raw result, and `harbor COMMAND --help` shows just that command. Statuses are backlog, todo, doing, review and done. A `DATE` is YYYY-MM-DD, `today`, `tomorrow`, or `+N` for N days from today.
+Every command takes `--json` for the raw result (a refusal then comes out as `{"error": "…"}` on standard output, still with exit code 1), and `harbor COMMAND --help` shows just that command. Statuses are backlog, todo, doing, review and done. A `DATE` is YYYY-MM-DD, `today`, `tomorrow`, or `+N` for N days from today.
 
 When you belong to more than one harbor, say which: `--harbor NAME` on the command, or `harbor use NAME` once (it's saved with your sign-in; `harbor use none` forgets it). With neither, the commands ask rather than guess, so nothing lands in the wrong harbor. The full-screen app shares the same choice: it opens the harbor `harbor use` set, asks which one the first time if none is set, and a harbor you switch to in the app becomes the one the commands use.
 

package/bin/harbor.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { VERSION, run } from "../lib/cli.mjs";
 import { HarborError } from "../lib/mcp.mjs";
-import { plain } from "../lib/plain.mjs";
+import { jsonText, plain } from "../lib/plain.mjs";
 import { updateNotice } from "../lib/update.mjs";
 
 const argv = process.argv.slice(2);
@@ -24,10 +24,12 @@ run(argv).then(
       err instanceof HarborError ||
       err?.name === "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(
-      `${plain(known ? err.message : `Something went wrong: ${err?.message ?? err}`)}\n`,
-    );
+    const message = known ? err.message : `Something went wrong: ${err?.message ?? err}`;
+    // With --json a script or agent reads the refusal as data, on stdout like
+    // a result; jsonText keeps it exact. Otherwise Harbor's refusals can quote
+    // a task's title, so they're printed plain.
+    if (argv.includes("--json")) process.stdout.write(`${jsonText({ error: message })}\n`);
+    else process.stderr.write(`${plain(message)}\n`);
     await tell();
     process.exit(1);
   },

package/dist/app.mjs

@@ -942,7 +942,7 @@ function stepsFor(kind, data, ctx, me) {
 				key: "name",
 				label: "Name",
 				kind: "text",
-				placeholder: "Fall catalogue shoot"
+				placeholder: "e.g. Fall catalogue shoot"
 			},
 			...ctx.programId ? [] : [{
 				key: "programId",
@@ -977,7 +977,7 @@ function stepsFor(kind, data, ctx, me) {
 				key: "name",
 				label: "Name",
 				kind: "text",
-				placeholder: "Spring range"
+				placeholder: "e.g. Spring range"
 			},
 			...ctx.portfolioId ? [] : [{
 				key: "portfolioId",
@@ -1005,7 +1005,7 @@ function stepsFor(kind, data, ctx, me) {
 			key: "name",
 			label: "Name",
 			kind: "text",
-			placeholder: "Samples approved"
+			placeholder: "e.g. Samples approved"
 		}, {
 			key: "dueDate",
 			label: "Due",
@@ -2349,7 +2349,7 @@ function Editor({ label, edit, done }) {
 	if (edit.kind === "date") return /* @__PURE__ */ jsx(TextField, {
 		label,
 		initial: edit.initial ?? "",
-		placeholder: "2026-10-14, today, tomorrow, +3, none",
+		placeholder: "YYYY-MM-DD, today, tomorrow, +3, none",
 		hint: error ?? "A date, today, tomorrow, +3 for three days on, or none",
 		onCancel: done,
 		onSubmit: (text) => {
@@ -2505,7 +2505,7 @@ function Stepper({ title, steps, width, onDone, onCancel }) {
 			onPick: next
 		}, step.key) : /* @__PURE__ */ jsx(TextField, {
 			label,
-			placeholder: step.kind === "date" ? "2026-10-14, today, +30" : step.kind === "text" ? step.placeholder : void 0,
+			placeholder: step.kind === "date" ? "YYYY-MM-DD, today, +30" : step.kind === "text" ? step.placeholder : void 0,
 			hint: error ?? (step.optional ? "Enter to skip · Esc to leave it" : void 0),
 			onCancel,
 			onSubmit: (text) => {
@@ -5787,7 +5787,7 @@ function DueField({ initial, today, onSubmit, onCancel }) {
 		children: /* @__PURE__ */ jsx(TextField, {
 			label: "Due",
 			initial,
-			placeholder: "2026-10-14, today, tomorrow, +3, none",
+			placeholder: "YYYY-MM-DD, today, tomorrow, +3, none",
 			hint: error ?? "A date, today, tomorrow, +3 for three days on, or none",
 			onCancel,
 			onSubmit: (text) => {

package/lib/cli.mjs

@@ -16,7 +16,15 @@ import {
   writeCredentials,
   writeSettings,
 } from "./config.mjs";
-import { harbors, myWork, taskLine, taskList, todayLocal } from "./format.mjs";
+import {
+  harbors,
+  myWork,
+  programTree,
+  projectList,
+  taskLine,
+  taskList,
+  todayLocal,
+} from "./format.mjs";
 import { colourDepth, logoLines } from "./logo.mjs";
 import { HarborError, createClient } from "./mcp.mjs";
 import { jsonText, plain } from "./plain.mjs";
@@ -32,11 +40,17 @@ export const HELP = `harbor: Harbor from the terminal
   harbor theme [auto|light|dark]              the app's colours
   harbor --version                            which version this is
 
+  harbor programs                             programs and their projects
+  harbor projects [words] [--program P]       projects with health and open work
   harbor mine                                 what's on you, late first
   harbor tasks [words] [--project P] [--assignee me|none|NAME]
                      [--late] [--status S,S]
   harbor show TASK                            one task (TASK: a key like RR-42)
 
+  harbor program "NAME" [--portfolio P] [--lead me|NAME] [--starts DATE]
+                       [--ends DATE]
+  harbor project "NAME" --program P [--lead me|NAME] [--starts DATE]
+                       [--ends DATE] [--budget N]
   harbor add "TITLE" --project P [--assignee me|NAME] [--due DATE]
                      [--priority low|medium|high|urgent] [--status S]
                      [--over-limit]
@@ -147,6 +161,12 @@ const FLAG = {
   title: "--title",
   project: "--project",
   program: "--program",
+  portfolio: "--portfolio",
+  lead: "--lead",
+  starts: "--starts",
+  ends: "--ends",
+  budget: "--budget",
+  name: "the name",
   owner: "--owner",
   impact: "--impact",
   probability: "--probability",
@@ -502,6 +522,69 @@ export async function run(argv, io = {}) {
       out(plain(`Commands now use ${hits[0].name}.`));
       return 0;
     }
+    case "programs": {
+      const { positionals, harbor } = parse(spec());
+      none(positionals);
+      return call("harbor_overview", { harbor }, programTree);
+    }
+    case "projects": {
+      const { positionals, values, harbor } = parse(spec([], ["program"]));
+      return call(
+        "list_projects",
+        {
+          harbor,
+          query: positionals.join(" ") || undefined,
+          program: values.program,
+          limit: 100,
+        },
+        projectList,
+      );
+    }
+    case "program": {
+      const { positionals, values, harbor } = parse(
+        spec([], ["portfolio", "lead", "starts", "ends"]),
+      );
+      return call(
+        "create_program",
+        {
+          harbor,
+          name: text(positionals, "the program's name"),
+          portfolio: values.portfolio,
+          lead: values.lead,
+          starts: dueDate(values.starts),
+          ends: dueDate(values.ends),
+        },
+        (r) =>
+          `Opened the program ${r.created.name} (${r.created.starts} to ${r.created.ends}, lead ${r.created.lead ?? "nobody"}).`,
+      );
+    }
+    case "project": {
+      const { positionals, values, harbor } = parse(
+        spec([], ["program", "lead", "starts", "ends", "budget"]),
+      );
+      if (!values.program) throw new HarborError("Say which program: --program NAME.");
+      let budget;
+      if (values.budget !== undefined) {
+        budget = Number(values.budget.replace(/[,_$£€]/g, ""));
+        if (!Number.isFinite(budget) || budget < 0) {
+          throw new HarborError("--budget is a number, like 25000.");
+        }
+      }
+      return call(
+        "create_project",
+        {
+          harbor,
+          name: text(positionals, "the project's name"),
+          program: values.program,
+          lead: values.lead,
+          starts: dueDate(values.starts),
+          ends: dueDate(values.ends),
+          budget,
+        },
+        (r) =>
+          `Opened the project ${r.created.name} in ${r.created.program} (${r.created.starts} to ${r.created.ends}, lead ${r.created.lead ?? "nobody"}). Add work with harbor add "TITLE" --project "${r.created.name}".`,
+      );
+    }
     case "mine": {
       const { positionals, harbor } = parse(spec());
       none(positionals);

package/lib/format.mjs

@@ -69,6 +69,58 @@ export function taskList(r, opts) {
   return r.tasks.map((t) => taskLine(t, opts)).join("\n") + more;
 }
 
+const HEALTH = { "on-track": "on track", "at-risk": "at risk", "off-track": "off track" };
+const health = (h) => HEALTH[h] ?? h ?? null;
+
+/** Each portfolio's programs and their projects, indented, as harbor_overview gives them. */
+export function programTree(r) {
+  const portfolios = r.portfolios ?? [];
+  if (!portfolios.some((pf) => pf.programs.length)) {
+    return 'No programs yet. Open one with harbor program "NAME".';
+  }
+  const out = [];
+  for (const pf of portfolios) {
+    if (portfolios.length > 1) out.push(pf.name);
+    const pad = portfolios.length > 1 ? "  " : "";
+    for (const pg of pf.programs) {
+      const bits = [health(pg.health), pg.ends ? `ends ${pg.ends}` : null].filter(Boolean);
+      out.push(`${pad}${pg.name}  (${bits.join(" · ")})`);
+      for (const pj of pg.projects) {
+        const work = [
+          health(pj.health),
+          `${pj.openTasks} open`,
+          pj.lateTasks ? `${pj.lateTasks} late` : null,
+          pj.ends ? `ends ${pj.ends}` : null,
+        ].filter(Boolean);
+        out.push(`${pad}  ${pj.name}  (${work.join(" · ")})`);
+      }
+      if (!pg.projects.length) out.push(`${pad}  no projects yet`);
+    }
+  }
+  return out.join("\n");
+}
+
+/** Projects one per line, name first so it can be passed to --project. */
+export function projectList(r) {
+  if (!r.projects?.length) return "No projects match.";
+  const more = r.total > r.projects.length ? `\n…and ${r.total - r.projects.length} more.` : "";
+  return (
+    r.projects
+      .map((p) => {
+        const late = p.tasks.late ? `, ${p.tasks.late} late` : "";
+        const bits = [
+          p.program,
+          health(p.health),
+          `${p.tasks.total - p.tasks.done} open${late}`,
+          p.owner,
+          p.ends ? `ends ${p.ends}` : null,
+        ].filter(Boolean);
+        return `${p.name}  (${bits.join(" · ")})`;
+      })
+      .join("\n") + more
+  );
+}
+
 export function harbors(r) {
   const list = r.harbors ?? [];
   if (!list.length) return "You aren't in any harbor yet. Run harbor to make one.";

package/package.json

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