@harborppm/cli 0.9.2 → 0.10.0

package/README.md

@@ -64,10 +64,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 +87,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) => {
@@ -3068,11 +3068,12 @@ function inboxOf(data, personId, now = clockNow()) {
 			return who ? firstName(who.name) : "Someone";
 		}))];
 		const blocked = waiting.length === 1 ? `“${waiting[0].title}”` : `${waiting.length} tasks`;
+		const upstream = openBlockerNames(blocker, data.tasks);
 		pings.push({
 			id: waiting.length === 1 ? `wait:${waiting[0].id}` : `wait:${blocker.id}:${shortHash(waiting.map((t) => t.id).sort().join(","))}`,
 			kind: "waiting",
 			title: `${listNames(names)} ${names.length === 1 ? "is" : "are"} waiting on you`,
-			detail: `${blocked} ${waiting.length === 1 ? "is" : "are"} blocked by “${blocker.title}”${project ? ` · ${project.name}` : ""}`,
+			detail: `${blocked} ${waiting.length === 1 ? "is" : "are"} blocked by “${blocker.title}”${project ? ` · ${project.name}` : ""}${upstream ? `. Yours waits on ${upstream} first.` : ""}`,
 			at: waiting.reduce((latest, t) => t.createdAt > latest ? t.createdAt : latest, ""),
 			taskId: blocker.id,
 			personId: waiting[0].assigneeId,
@@ -3887,6 +3888,7 @@ const HELP = [
 	["u / r", "undo your last change / retry saving"],
 	["v", "on a project: board, list, budget"],
 	["m / R", "new milestone on a program / log a risk"],
+	["D", "show or hide Done projects and programs"],
 	["c / a", "on a task: comment / add a checklist step"],
 	["q", "quit (saves first)"]
 ];
@@ -4687,11 +4689,25 @@ function PersonPanel({ id, width, height, go, onClose }) {
 	});
 }
 
+//#endregion
+//#region src/lib/selectors.ts
+/** Projects (or programs) still running, and the ones set to Done, which lists tuck away until asked for. */
+function splitDone(items) {
+	const open = [];
+	const done = [];
+	for (const item of items) (item.health === "done" ? done : open).push(item);
+	return {
+		open,
+		done
+	};
+}
+
 //#endregion
 //#region src/tui/views/program.tsx
 /**
 * One program: its health (and why, when set by hand), next move, its
-* projects and its milestones. ←→ between the two lists.
+* projects and its milestones. ←→ between the two lists. Projects set to
+* Done stay out of the list until D shows them.
 */
 function ProgramView({ programId, active, width, height, go, onBack }) {
 	const { store, today } = useDeps();
@@ -4701,7 +4717,9 @@ function ProgramView({ programId, active, width, height, go, onBack }) {
 	const milestones = useHarbor((s) => s.milestones);
 	const people = useHarbor((s) => s.people);
 	const portfolio = useHarbor((s) => s.portfolios.find((p) => p.id === program?.portfolioId));
-	const mine = useMemo(() => projects.filter((p) => p.programId === programId), [projects, programId]);
+	const [showDone, setShowDone] = useState(false);
+	const split = useMemo(() => splitDone(projects.filter((p) => p.programId === programId)), [projects, programId]);
+	const mine = showDone ? [...split.open, ...split.done] : split.open;
 	const marks = useMemo(() => milestonesOf({ milestones }, programId, today()), [
 		milestones,
 		programId,
@@ -4720,6 +4738,10 @@ function ProgramView({ programId, active, width, height, go, onBack }) {
 		if (input === "n") return go.create("project", { programId });
 		if (input === "m") return go.create("milestone", { programId });
 		if (input === "R") return go.create("raid", {});
+		if (input === "D" && split.done.length > 0) {
+			setSide("projects");
+			return setShowDone((v) => !v);
+		}
 		if (side === "projects") {
 			if (key.upArrow || input === "k") setPAt((i) => step(i, -1, mine.length));
 			else if (key.downArrow || input === "j") setPAt((i) => step(i, 1, mine.length));
@@ -4794,12 +4816,12 @@ function ProgramView({ programId, active, width, height, go, onBack }) {
 				marginRight: 1,
 				children: [
 					/* @__PURE__ */ jsx(Heading, {
-						right: `${mine.length}`,
+						right: split.done.length > 0 ? `${mine.length} · ${split.done.length} done ${showDone ? "shown" : "hidden"} (D)` : `${mine.length}`,
 						children: side === "projects" ? "› Projects" : "  Projects"
 					}),
 					mine.length === 0 ? /* @__PURE__ */ jsx(Text, {
 						color: theme.muted,
-						children: "None yet. n adds one."
+						children: split.done.length > 0 ? "Every project here is done. D shows them." : "None yet. n adds one."
 					}) : null,
 					windowOf(mine, pAt, rows).items.map((p) => {
 						const on = active && side === "projects" && p.id === project?.id;
@@ -4873,18 +4895,21 @@ function ProgramView({ programId, active, width, height, go, onBack }) {
 		]
 	});
 }
-/** One portfolio: its health and its programs, each with theirs. */
+/** One portfolio: its health and its programs, each with theirs; Done ones wait for D. */
 function PortfolioView({ portfolioId, active, width, height, go, onBack }) {
 	const portfolio = useHarbor((s) => s.portfolios.find((p) => p.id === portfolioId));
 	const programs = useHarbor((s) => s.programs);
 	const projects = useHarbor((s) => s.projects);
-	const list = useMemo(() => programs.filter((p) => p.portfolioId === portfolioId), [programs, portfolioId]);
+	const [showDone, setShowDone] = useState(false);
+	const split = useMemo(() => splitDone(programs.filter((p) => p.portfolioId === portfolioId)), [programs, portfolioId]);
+	const list = showDone ? [...split.open, ...split.done] : split.open;
 	const [at, setAt] = useState(0);
 	const program = list[Math.min(at, list.length - 1)];
 	useInput((input, key) => {
 		if (key.escape || key.backspace) return onBack();
 		if (input === "e") return go.openPanel("portfolio", portfolioId);
 		if (input === "n") return go.create("program", { portfolioId });
+		if (input === "D" && split.done.length > 0) return setShowDone((v) => !v);
 		if (key.upArrow || input === "k") setAt((i) => step(i, -1, list.length));
 		else if (key.downArrow || input === "j") setAt((i) => step(i, 1, list.length));
 		else if (key.return && program) go.openProgram(program.id);
@@ -4928,12 +4953,12 @@ function PortfolioView({ portfolioId, active, width, height, go, onBack }) {
 			}),
 			/* @__PURE__ */ jsx(Text, { children: " " }),
 			/* @__PURE__ */ jsx(Heading, {
-				right: `${list.length} program${list.length === 1 ? "" : "s"}`,
+				right: `${list.length} program${list.length === 1 ? "" : "s"}${split.done.length > 0 ? ` · ${split.done.length} done ${showDone ? "shown" : "hidden"} (D)` : ""}`,
 				children: "Programs"
 			}),
 			list.length === 0 ? /* @__PURE__ */ jsx(Text, {
 				color: theme.muted,
-				children: "None yet. n adds one."
+				children: split.done.length > 0 ? "Every program here is done. D shows them." : "None yet. n adds one."
 			}) : null,
 			windowOf(list, at, height - 5).items.map((p) => {
 				const on = active && p.id === program?.id;
@@ -5762,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.2",
+  "version": "0.10.0",
   "description": "Harbor from the terminal: a full-screen app with everything, plus commands for scripts and agents.",
   "keywords": [
     "harbor",