@harborppm/cli 0.66.0 → 0.69.0

package/README.md

@@ -46,7 +46,7 @@ It runs on the same engine as the website: health, task keys, limits and undo wo
 
 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.
+`harbor help` starts with the dozen commands most people need; `harbor help all` lists every one. It 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
 

package/dist/app.mjs

@@ -3128,6 +3128,7 @@ function tideOptions(data) {
 * "what if Sam joined" (src/lib/dry-dock.ts).
 */
 function tideForecast(project, tasks, now, opts = {}) {
+	if (tasks.length === 0) return { kind: "empty" };
 	const remaining = tasks.filter((t) => t.status !== "done").length;
 	if (remaining === 0) return { kind: "done" };
 	if (project.health === "paused") return {
@@ -3201,6 +3202,7 @@ function dueAfterFinish(tide) {
 /** Why there's no forecast, for the states without one. */
 function tideQuiet(tide) {
 	switch (tide.kind) {
+		case "empty": return "No tasks yet, so there's nothing to forecast.";
 		case "done": return "Every task is done.";
 		case "paused": return "Paused, so its pace says nothing about when it ends.";
 		case "no-pace": return `Nothing finished in the last ${6} weeks, so there's no pace to forecast from yet.`;
@@ -6437,20 +6439,23 @@ function PriorityMark({ priority }) {
 		children: priority === "urgent" ? "!!" : priority === "high" ? "!" : "↓"
 	});
 }
+/** A heading keeps its own width, up to this much of the row; the hints beside it shorten first. */
+const HEADING_MAX = "70%";
 /** A section heading inside a screen. */
 function Heading({ children, right }) {
 	return /* @__PURE__ */ jsxs(Box, {
 		justifyContent: "space-between",
 		columnGap: 2,
 		children: [/* @__PURE__ */ jsx(Box, {
-			flexShrink: 1,
+			flexShrink: 0,
+			maxWidth: "70%",
 			children: /* @__PURE__ */ jsx(Text, {
 				bold: true,
 				wrap: "truncate-end",
 				children
 			})
 		}), right ? /* @__PURE__ */ jsx(Box, {
-			flexShrink: 2,
+			flexShrink: 1,
 			children: /* @__PURE__ */ jsx(Text, {
 				color: theme.muted,
 				wrap: "truncate-end",
@@ -9796,6 +9801,50 @@ var init_load = __esmMin((() => {
 	};
 }));
 
+//#endregion
+//#region src/lib/first-voyage.ts
+function isVoyageProject(projectId) {
+	return projectId === VOYAGE_PROJECT_ID;
+}
+var VOYAGE_PROJECT_ID, STEPS, voyageTaskId, SEEDED;
+var init_first_voyage = __esmMin((() => {
+	VOYAGE_PROJECT_ID = "voyage";
+	STEPS = [
+		{
+			step: "task",
+			title: "Add a task of your own",
+			description: "Press New, or the + at the top of a column on any board. Anything real will do. This ticks itself off when you add one."
+		},
+		{
+			step: "move",
+			title: "Move a task to In progress",
+			description: "Open Board above and drag a card along, or change its status in the task's panel. This one counts too. It ticks itself off."
+		},
+		{
+			step: "crew",
+			title: "Bring someone aboard, or tick this to skip",
+			description: "Invite from your menu or from People. Harbor is $49 a month for the whole crew, not per seat. Ticks itself off when someone's in People."
+		},
+		{
+			step: "terminal",
+			title: "Try Harbor in your terminal",
+			description: "Run `npx @harborppm/cli mine` (Node 22 or later) and sign in when your browser asks. `harbor` on its own opens the whole harbor full screen. Ticks itself off once the terminal is connected; skip it if a terminal isn't your thing."
+		},
+		{
+			step: "agent",
+			title: "Ask an AI app to add a task for you",
+			description: "Connect Claude, or any app that speaks MCP, at harborppm.com/ai, then ask it to add a task here. Harbor asks you first and History names the app. Ticks itself off once an app is connected."
+		},
+		{
+			step: "wrap",
+			title: "Mark this project Done, or delete it",
+			description: "That's the voyage. Set its health to Done to put it away, or delete it from Details. Your own work stays."
+		}
+	];
+	voyageTaskId = (step) => `voyage-${step}`;
+	SEEDED = new Set(STEPS.map((s) => voyageTaskId(s.step)));
+}));
+
 //#endregion
 //#region src/lib/handover.ts
 /** Everything a person carries that someone else would have to pick up, grouped in KIND_ORDER. */
@@ -10024,6 +10073,7 @@ var init_handover = __esmMin((() => {
 init_date_fns();
 init_indexes();
 init_raid();
+init_first_voyage();
 init_task_keys();
 init_load();
 init_date_text();
@@ -10084,6 +10134,7 @@ function lifeboats(data, now, opts = {}) {
 	const out = [];
 	for (const project of data.projects) {
 		if (project.health === "done" || project.health === "paused") continue;
+		if (isVoyageProject(project.id)) continue;
 		if (!inScope(project.programId)) continue;
 		const tasks = grouped.get(project.id) ?? [];
 		const open = tasks.filter((t) => t.status !== "done");
@@ -19518,7 +19569,7 @@ var init_passage = __esmMin((() => {
 	isPassage = (r) => r.kind === "passage";
 	iso$1 = (d) => todayISO(d);
 	at = (day) => parseIso(`${day}T12:00:00`);
-	byDue = (a, b) => (a.dueDate ?? "9999").localeCompare(b.dueDate ?? "9999") || a.title.localeCompare(b.title);
+	byDue = (a, b) => (a.dueDate ?? "9999").localeCompare(b.dueDate ?? "9999");
 	DAY_WORDS = [
 		"mon",
 		"tue",
@@ -21942,104 +21993,6 @@ var init_session = __esmMin((() => {
 	init_format();
 }));
 
-//#endregion
-//#region src/lib/sample-project.ts
-function sampleProject(opts) {
-	const { ownerId, today, now, makeId } = opts;
-	const day = (n) => todayISO(addDays(parseDate$1(today), n));
-	const end = opts.programEnd && opts.programEnd < day(30) ? opts.programEnd : day(30);
-	const projectId = makeId("pj");
-	const project = {
-		id: projectId,
-		programId: opts.programId,
-		name: SAMPLE_PROJECT_NAME,
-		description: "A project to try things on. Move cards, add tasks, change dates. Delete it from Details when you’re done.",
-		swatch: "sea",
-		ownerId,
-		health: "on-track",
-		startDate: today,
-		endDate: end,
-		budget: 0,
-		spent: 0
-	};
-	const task = (title, status, o = {}) => ({
-		id: makeId("t"),
-		projectId,
-		title,
-		description: o.description ?? "",
-		status,
-		priority: o.priority ?? "medium",
-		assigneeId: ownerId,
-		dueDate: o.due == null ? null : day(o.due),
-		createdAt: now,
-		completedAt: status === "done" ? now : null,
-		checklist: (o.checklist ?? []).map(([t, done]) => ({
-			id: makeId("ck"),
-			title: t,
-			done
-		})),
-		blockedById: o.waitsOn ?? null,
-		blockedByIds: o.waitsOn ? [o.waitsOn] : []
-	});
-	const draft = task("Draft the new home page", "doing", {
-		description: "A sample card. Tick the checklist, leave a comment, or drag it to Review on the board.",
-		due: 3,
-		priority: "high",
-		checklist: [
-			["Headline and one line under it", true],
-			["Three reasons to stay", false],
-			["One clear button", false]
-		]
-	});
-	return {
-		project,
-		tasks: [
-			task("Agree what the refresh is for", "done", { description: "Finished. Move it back if it turns out it wasn’t." }),
-			task("List the pages people actually use", "done"),
-			draft,
-			task("Write the pricing page copy", "review", {
-				description: "Waiting for a second pair of eyes. Move it to Done when it reads well.",
-				due: 5
-			}),
-			task("Pick the photos", "todo", {
-				description: "Hand this one to someone else from the card’s Owner field.",
-				due: 7
-			}),
-			task("Check every page on a phone", "todo", {
-				description: "Waits on the home page draft, so it shows as waiting until that card is done.",
-				due: 10,
-				waitsOn: draft.id
-			}),
-			task("Send old links to the new pages", "backlog", { description: "No date yet. Backlog is for what isn’t planned." }),
-			task("Tell customers what changed", "backlog", { priority: "low" })
-		],
-		raidItems: [{
-			id: makeId("r"),
-			kind: "risk",
-			projectId,
-			title: "Photos may not be cleared in time",
-			description: "A sample risk. If the photos aren’t licensed before launch, the home page ships with placeholders.",
-			severity: "medium",
-			status: "open",
-			ownerId,
-			dueDate: day(7),
-			probability: 3,
-			impact: 3,
-			mitigation: "Shortlist stock photos we already own as a fallback.",
-			createdById: ownerId,
-			createdAt: now,
-			updatedAt: now,
-			updates: []
-		}]
-	};
-}
-var SAMPLE_PROJECT_NAME;
-var init_sample_project = __esmMin((() => {
-	init_date_fns();
-	init_format();
-	SAMPLE_PROJECT_NAME = "Website refresh (sample)";
-}));
-
 //#endregion
 //#region src/lib/first-week.ts
 /** The program launch named for you, when nobody has renamed it yet. */
@@ -22108,7 +22061,7 @@ function hierarchySlice({ get, write }) {
 			get().log(`opened project ${row.name}`, `/projects/${id}`);
 			return id;
 		},
-		addSampleProject: () => {
+		addSampleProject: (sampleProject) => {
 			const state = get();
 			const program = state.programs[0];
 			if (!program) return null;
@@ -22483,7 +22436,6 @@ var init_hierarchy = __esmMin((() => {
 	init_shared();
 	init_hill();
 	init_charter_lines();
-	init_sample_project();
 	init_format();
 	init_empty();
 	init_first_week();
@@ -26127,7 +26079,7 @@ function changesFrom(data, project, flags, now) {
 	});
 	return changes;
 }
-const likely = (t) => t.kind === "forecast" ? t.likely ? shortDate(t.likely) : "not in 2 years" : t.kind === "done" ? "done" : "no pace yet";
+const likely = (t) => t.kind === "forecast" ? t.likely ? shortDate(t.likely) : "not in 2 years" : t.kind === "done" ? "done" : t.kind === "empty" ? "no tasks yet" : "no pace yet";
 const very = (t) => t.kind === "forecast" && t.veryLikely ? shortDate(t.veryLikely) : "-";
 /** What `harbor try` prints: the changes, then the two plans side by side. */
 function tryLines(data, project, changes, cmp, today) {
@@ -28026,7 +27978,8 @@ function ProjectView({ projectId, active, width, height, go, onBack }) {
 				justifyContent: "space-between",
 				columnGap: 2,
 				children: [/* @__PURE__ */ jsx(Box, {
-					flexShrink: 1,
+					flexShrink: 0,
+					maxWidth: "70%",
 					children: /* @__PURE__ */ jsxs(Text, {
 						wrap: "truncate-end",
 						children: [
@@ -28047,7 +28000,7 @@ function ProjectView({ projectId, active, width, height, go, onBack }) {
 						]
 					})
 				}), /* @__PURE__ */ jsx(Box, {
-					flexShrink: 2,
+					flexShrink: 1,
 					children: /* @__PURE__ */ jsxs(Text, {
 						color: theme.muted,
 						wrap: "truncate-end",
@@ -28141,7 +28094,9 @@ function ProjectView({ projectId, active, width, height, go, onBack }) {
 					const w = Math.floor((width - 2) / shownColumns.length);
 					const on = active && ci === col;
 					const r = Math.min(rowByCol[ci] ?? 0, Math.max(0, c.tasks.length - 1));
-					const view = windowOf(c.tasks, r, Math.max(1, Math.floor((body - 3) / 3)));
+					const room = body - 3;
+					const fits = Math.floor(room / 3) >= c.tasks.length;
+					const view = windowOf(c.tasks, r, Math.max(1, Math.floor((fits ? room : room - 2) / 3)));
 					const over = c.limit != null && c.all > c.limit;
 					return /* @__PURE__ */ jsxs(Box, {
 						flexDirection: "column",

package/lib/cli.mjs

@@ -286,6 +286,31 @@ export const HELP = `harbor: Harbor from the terminal
   and so can harbor fog --sweep's x (drop it), one task at a time.
 `;
 
+/**
+ * What `harbor help` shows first: the dozen commands a newcomer needs, then
+ * where the rest are. `harbor help all` is the whole list (HELP).
+ */
+export const START_HELP = `harbor: Harbor from the terminal
+
+  harbor                         the full-screen app, by keyboard
+  harbor signup                  new to Harbor: make an account
+  harbor login                   sign in (opens your browser once)
+
+  harbor mine                    what's on you, late first
+  harbor add "TITLE"             add a task (--project P, --due DATE)
+  harbor start TASK              move a task to In play (TASK: a key like RR-42)
+  harbor done TASK               finish it
+  harbor tasks [words]           find tasks across the harbor
+  harbor projects                projects with health and open work
+  harbor brief                   one letter: late work, live risks, what shipped
+  harbor open [TASK|PROJECT]     open it on the website
+  harbor invite EMAIL            invite someone to your harbor
+
+  harbor help all                every command (forecasts, risks, weekly plans,
+                                 plans kept in a repo, and more)
+  harbor help COMMAND            just that one, with all its options
+`;
+
 export const VERSION = JSON.parse(
   readFileSync(new URL("../package.json", import.meta.url), "utf8"),
 ).version;
@@ -415,11 +440,28 @@ const level = (v, name) => {
 const nullable = (v) => (v === "none" ? null : v);
 const REPEAT_WORD = { weekly: "every week", biweekly: "every two weeks", monthly: "every month" };
 
-/** --due as people say it: today, tomorrow, +3, or a date. Anything else goes to Harbor to judge. */
+const WEEKDAYS = ["sunday", "monday", "tuesday", "wednesday", "thursday", "friday", "saturday"];
+
+/** "fri", "Friday": how many days until that weekday comes round (today counts). */
+function daysToWeekday(v, today) {
+  const w = v.toLowerCase();
+  if (w.length < 3) return null;
+  const i = WEEKDAYS.findIndex((d) => d.startsWith(w));
+  return i < 0 ? null : (i - today.getDay() + 7) % 7;
+}
+
+/** --due as people say it: today, tomorrow, friday, +3, or a date. Anything else goes to Harbor to judge. */
 export function dueDate(v, today = new Date()) {
   if (v === undefined || v === null) return v;
   const words = { today: 0, tomorrow: 1 };
-  const days = v in words ? words[v] : /^\+\d{1,3}$/.test(v) ? Number(v.slice(1)) : null;
+  const days =
+    v in words
+      ? words[v]
+      : /^\+\d{1,3}$/.test(v)
+        ? Number(v.slice(1))
+        : /^[a-z]+$/i.test(v)
+          ? daysToWeekday(v, today)
+          : null;
   if (days === null) return v;
   const d = new Date(today.getFullYear(), today.getMonth(), today.getDate() + days);
   return todayLocal(d);
@@ -513,7 +555,7 @@ export function hint(message, project) {
           (_, list) => `pick one of ${list.replace(/"/g, "").split("|").join(", ")}`,
         )
         // The CLI reads today, tomorrow and +N before Harbor sees the date.
-        .replace(/^a date as YYYY-MM-DD$/, "a date like 2026-11-30, today, tomorrow or +N days");
+        .replace(/^a date as YYYY-MM-DD$/, "a date like 2026-11-30, today, tomorrow, friday or +N days");
       if (!seen.has(flag)) seen.set(flag, said);
     }
     return [...seen].map(([flag, why]) => `${flag}: ${why}`).join("\n");
@@ -780,7 +822,9 @@ const DETAIL = {
     "                                         names them",
     "",
     "  FILE is CSV or tab-separated: a spreadsheet, or a Jira, Asana or Linear",
-    "  export. It needs a column of titles; rows naming a Project column go",
+    "  export. A Trello board's JSON export works too (Menu, then Print, export",
+    "  and share, then Export as JSON): each list becomes a status, and the",
+    "  board a project. It needs a column of titles; rows naming a Project go",
     "  there. People it names who aren't in the harbor are added unless you say",
     "  --no-people. A task already in its project is left alone: by its key",
     "  (a Key column, as harbor export writes) or by title.",
@@ -1133,6 +1177,22 @@ const DETAIL = {
   ],
 };
 
+/**
+ * A Trello board's JSON export without its activity log, which is most of the
+ * file and none of what an import reads; anything else is sent as it is.
+ */
+export function trelloLean(text) {
+  if (!text.trimStart().startsWith("{")) return text;
+  try {
+    const board = JSON.parse(text);
+    if (!Array.isArray(board?.cards) || !Array.isArray(board?.lists)) return text;
+    const { name, cards, lists, members } = board;
+    return JSON.stringify({ name, cards, lists, members });
+  } catch {
+    return text;
+  }
+}
+
 /** The lines of the help about one command, or null when it has none. */
 export function commandHelp(command) {
   const lines = HELP.split("\n");
@@ -1183,12 +1243,28 @@ function distance(a, b) {
   return d[a.length][b.length];
 }
 
+/** What someone who knows the website, or a feature's name, might type. */
+const OTHER_NAMES = {
+  today: "harbor mine lists what's on you, late first; harbor week plans your days.",
+  inbox: "harbor catchup says what was handed to you and what moved.",
+  people: "harbor lifeboats, harbor clock and harbor ashore cover the crew; the app's People screen (harbor, then 6) shows everyone's load.",
+  crew: "harbor invite EMAIL brings someone aboard; the app's Crew screen (harbor, then C) lists who's on it.",
+  longpole: "harbor why PROJECT shows what's holding it up.",
+  "long-pole": "harbor why PROJECT shows what's holding it up.",
+  pilot: "harbor show TASK says the date its owner's queue suggests; --due pilot on add or edit takes it.",
+  dock: "harbor try PROJECT is the dry dock.",
+  "dry-dock": "harbor try PROJECT is the dry dock.",
+};
+
 /** A mistyped command, with the one it was probably meant to be. */
 export function noCommand(name) {
   if (name.startsWith("-")) return `${name} goes after a command, like harbor mine ${name}.`;
   // A plural kind reads the register, not the command that writes one.
   if (["decisions", "issues"].includes(name))
     return `No command "${name}". harbor risks --kind ${name.slice(0, -1)} lists them.`;
+  // Words for things the website has a page for, or that go by another name here.
+  const other = OTHER_NAMES[name.toLowerCase()];
+  if (other) return `No command "${name}". ${other}`;
   const near = COMMANDS.filter((c) => distance(name, c) <= (c.length > 4 ? 2 : 1));
   const guess = near.length === 1 ? ` Did you mean harbor ${near[0]}?` : "";
   return `No command "${name}".${guess} Run harbor help.`;
@@ -1266,7 +1342,8 @@ export async function run(argv, io = {}) {
 
   if (command === "help" || command === "--help" || command === "-h") {
     // `harbor help mine`: that command's help, as `harbor mine --help` gives it.
-    if (rest[0] && rest[0] !== "help") {
+    const all = rest[0] === "all" || rest[0] === "help" || rest.includes("--all");
+    if (rest[0] && !all) {
       const help = commandHelp(rest[0]);
       if (help === null) throw new HarborError(noCommand(rest[0]));
       out(help);
@@ -1280,7 +1357,8 @@ export async function run(argv, io = {}) {
       dim(`cli ${VERSION} · harborppm.com`),
     ]);
     // The banner says what the help's first line does.
-    out(top ? `${top}${HELP.slice(HELP.indexOf("\n"))}` : HELP);
+    const text = all ? HELP : START_HELP;
+    out(top ? `${top}${text.slice(text.indexOf("\n"))}` : text);
     return 0;
   }
 
@@ -1295,7 +1373,7 @@ export async function run(argv, io = {}) {
     if (help === null && command !== "app") {
       throw new HarborError(noCommand(command));
     }
-    out(help ?? HELP);
+    out(help ?? START_HELP);
     return 0;
   }
 
@@ -1309,7 +1387,7 @@ export async function run(argv, io = {}) {
   if (!command || command === "app" || bridgeApp) {
     const terminal = inTerminal;
     if (!command && !terminal) {
-      out(HELP);
+      out(START_HELP);
       return 0;
     }
     if (!terminal) throw new HarborError("The full-screen app needs a terminal.");
@@ -1596,7 +1674,7 @@ export async function run(argv, io = {}) {
           veryLikely: f?.veryLikely ?? null,
           chanceByEnd: f?.chanceByEnd ?? null,
           tasksPerWeek: f?.perWeek ?? null,
-          // Why there are no dates, when there aren't: no pace yet, paused, done.
+          // Why there are no dates, when there aren't: no tasks yet, no pace yet, paused, done.
           noForecast: f ? null : s.tide.kind,
         };
       };
@@ -2309,7 +2387,9 @@ export async function run(argv, io = {}) {
         added.push(r);
       }
       await stalePromptCache(env);
-      if (asJson) out(jsonText(added.length === 1 ? added[0] : { added }));
+      // `added` is always the list, so a script reads one key however many
+      // titles it sent; one title also keeps its `created` at the top.
+      if (asJson) out(jsonText(added.length === 1 ? { ...added[0], added } : { added }));
       else
         out(
           plain(
@@ -2642,6 +2722,7 @@ export async function run(argv, io = {}) {
       } catch {
         throw new HarborError(`Can't read ${file}.`);
       }
+      csv = trelloLean(csv);
       return call(
         "import_tasks",
         {

package/lib/format.mjs

@@ -581,7 +581,7 @@ export function bridgeText(r) {
   );
   for (const p of r.projects ?? []) {
     const facts = [
-      p.health,
+      p.health?.replace(/-/g, " "),
       p.lead,
       p.ends ? `ends ${p.ends}` : null,
       `${p.late} late of ${p.open} open`,

package/package.json

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