@harborppm/cli 0.9.3 → 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) => {
@@ -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.0",
   "description": "Harbor from the terminal: a full-screen app with everything, plus commands for scripts and agents.",
   "keywords": [
     "harbor",