@harborppm/cli 0.66.0 → 0.68.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.`;
@@ -9796,6 +9798,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 +10070,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 +10131,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 +19566,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 +21990,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 +22058,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 +22433,6 @@ var init_hierarchy = __esmMin((() => {
 	init_shared();
 	init_hill();
 	init_charter_lines();
-	init_sample_project();
 	init_format();
 	init_empty();
 	init_first_week();
@@ -26127,7 +26076,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) {

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;
@@ -780,7 +805,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 +1160,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");
@@ -1266,7 +1309,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 +1324,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 +1340,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 +1354,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 +1641,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 +2354,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 +2689,7 @@ export async function run(argv, io = {}) {
       } catch {
         throw new HarborError(`Can't read ${file}.`);
       }
+      csv = trelloLean(csv);
       return call(
         "import_tasks",
         {

package/package.json

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