@harborppm/cli 0.65.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
 
@@ -189,7 +189,7 @@ harbor review [WORDS] [--mine|--owner NAME] [--portfolio P] [--done]
                                             the review: programs worst first, with next moves
                                             (reads only; harbor submit moves a task to In review)
 harbor thanks [TASK "LINE"] [--to NAME]     a one-line thanks for a task (--milestone, --decision);
-                                            on its own, the thanks you were given this month
+                                            on its own, the thanks you were given in the last 30 days
 harbor bridge                               run the review as a meeting: one project a screen,
                                             what changed since the last one, log decisions,
                                             actions and risks live, post the summary to chat

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.`;
@@ -3285,6 +3287,7 @@ function barnaclesOf(project, tasks, people, now, slip = null) {
 	return {
 		since,
 		from,
+		settling: from === "start" && since.slice(0, 10) > today,
 		planned,
 		added: added.length,
 		share: planned > 0 ? added.length / planned : null,
@@ -9795,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. */
@@ -10023,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();
@@ -10083,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");
@@ -19517,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",
@@ -19581,6 +19630,7 @@ function barnaclesData(b) {
 	return {
 		measuredFrom: b.from === "baseline" ? "when the baseline was set" : "a week after its first task was made",
 		since: b.since,
+		settling: b.settling,
 		planned: b.planned,
 		added: b.added,
 		addedPercent: b.share == null ? null : Math.round(b.share * 100),
@@ -20950,7 +21000,7 @@ const HARBOR_TOOLS = [
 	tool({
 		name: "scope_growth",
 		title: "Barnacles: work added since the plan was set",
-		description: "How much a project's plan has grown since it was set (barnacles): tasks made after the baseline was set (or, without a baseline time, after the project's first week of tasks), as a count and a percent of what was planned, by week (weekOf is a Monday) and by who added them (who is null for tasks made before Harbor kept track, or by a form). daysOfWork puts them at the crew's pace (tasks finished a week over the last six); slipDays is how late the project runs against its planned end (the likely finish at that pace, or the end date's move from the baseline), and daysLine says how much of it the added work explains." + DATA_NOTE,
+		description: "How much a project's plan has grown since it was set (barnacles): tasks made after the baseline was set (or, without a baseline time, after the project's first week of tasks), as a count and a percent of what was planned, by week (weekOf is a Monday) and by who added them (who is null for tasks made before Harbor kept track, or by a form). daysOfWork puts them at the crew's pace (tasks finished a week over the last six); slipDays is how late the project runs against its planned end (the likely finish at that pace, or the end date's move from the baseline), and daysLine says how much of it the added work explains. settling is true while a project without a baseline is still in its first week (since is in the future): nothing counts as added yet, and setting a baseline counts from now." + DATA_NOTE,
 		input: object({
 			harbor: harborArg,
 			project: string().min(1).max(200).describe("Project id, name or key.")
@@ -21940,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. */
@@ -22106,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;
@@ -22481,7 +22433,6 @@ var init_hierarchy = __esmMin((() => {
 	init_shared();
 	init_hill();
 	init_charter_lines();
-	init_sample_project();
 	init_format();
 	init_empty();
 	init_first_week();
@@ -26125,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

@@ -205,7 +205,7 @@ export const HELP = `harbor: Harbor from the terminal
                                               the review: programs worst first,
                                               each with its next move (reads
                                               only; harbor submit moves a task)
-  harbor thanks [--all] [--given]             thanks you were given this month
+  harbor thanks [--all] [--given]             your thanks, last 30 days
   harbor thanks TASK "LINE" [--to NAME]       a one-line thanks for a task
   harbor thanks --milestone NAME|--decision TITLE "LINE" [--to NAME]
                                               the same for a milestone or a
@@ -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/lib/format.mjs

@@ -643,6 +643,13 @@ export function whyText(r) {
 /** A project's barnacles, as scope_growth answers it: the growth, its cost in days, by week and by who. */
 export function barnaclesText(r) {
   const head = [`Barnacles · ${r.project}`];
+  if (r.settling) {
+    head.push(
+      `The plan is still being written: ${r.planned} task${r.planned === 1 ? "" : "s"} so far, and nothing counts as added until ${monthDay(r.since)}, a week after its first task.`,
+      `harbor baseline "${r.key ?? r.project}" --set counts from now instead.`,
+    );
+    return head.join("\n");
+  }
   if (!r.added) {
     head.push(`Nothing added since the plan was set (${r.since.slice(0, 10)}): ${r.planned} task${r.planned === 1 ? "" : "s"}, as planned.`);
     return head.join("\n");
@@ -1198,7 +1205,7 @@ export function catchupText(r) {
         m.added ? `${m.added} added` : null,
         m.health ? `now ${HEALTH[m.health.to] ?? m.health.to} (was ${HEALTH[m.health.from] ?? m.health.from})` : null,
       ].filter(Boolean);
-      out.push(`  ${m.project}: ${bits.join(", ")}`);
+      out.push(`  ${m.key ? `${m.key} ` : ""}${m.project}: ${bits.join(", ")}`);
     }
   }
   const more = r.handed.length > r.lookFirst.filter((l) => l.kind === "handed").length;

package/package.json

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