@harborppm/cli 0.54.0 → 0.55.0

package/README.md

@@ -149,7 +149,8 @@ harbor project "NAME" --program P [--lead me|NAME] [--starts DATE]
                                             --from: dead reckoning, its tasks due when
                                             they really finished in that project
 harbor add "TITLE" --project P [--assignee me|NAME] [--due DATE]
-                   [--priority low|medium|high|urgent] [--status S] [--over-limit]
+                   [--priority low|medium|high|urgent] [--status S] [--comment TEXT]
+                   [--over-limit]               no TITLE: one title a line from stdin
 harbor start TASK | submit TASK | done TASK [--confirm] [--over-limit]
 harbor edit TASK [--title T] [--assignee me|none|NAME] [--due DATE|none]
                  [--priority P] [--status S] [--notes TEXT]
@@ -189,6 +190,8 @@ harbor note PROJECT ["NOTE"] [--opens DATE|--milestone NAME|--off-track]
 harbor sound TASK [DAYS] [--why TEXT] [--ask NAMES|crew] [--settle DAYS]
 harbor soundings [PROJECT]
 harbor limit PROJECT [COLUMN N|none]
+harbor week [--next|--last|--week DATE] [--review]
+harbor week TASK DAY [--hours N] | week TASK --off [DAY] | week --day-hours N
 harbor init [PROJECT] [--hook] [--dry-run]  a project's tasks as files in this repository
 harbor init --local [NAME]                  a plan in this folder alone, no account
 harbor sync [--quiet] [--dry-run]           the files and the website, in step both ways
@@ -211,6 +214,10 @@ harbor agent report TASK "WHAT YOU DID" [--start] [--agent NAME]
 
 Agents on the crew: put an AI app on People with Add an agent and assign it tasks like anyone else. An agent working through the CLI (Claude Code, say) runs `harbor agent` for its tasks, in progress first, with their notes, checklists and latest comments. When it's done, `harbor agent report RR-4 "Drafted 12 questions; two need Dana"` adds its note as the agent's comment and moves the task to In review for a person to check. An agent never marks its own work Done.
 
+`harbor week` is your own week, and only you see it: Monday to Friday with the tasks you put on each day, the hours each should take against the hours you work (`--day-hours 8`; 7 unless you say), a warning on a day that's too full, and your open tasks not on a day yet. `harbor week RR-42 wed --hours 3` puts a task on Wednesday (`--next` for next week), `harbor week RR-42 --off` takes it off the week, and from Friday (or with `--review`) it says what you planned against what you finished. The website's Your week is the same plan, with drag and drop.
+
+`harbor add --project Trail --comment "From Monday's call" < list.txt` adds one task per line of the file, each with the comment.
+
 `harbor limit RR` prints how many tasks each of a board's columns takes at once; `harbor limit RR doing 8` changes one (1 to 20, or `none` for no limit), if you own the harbor. `harbor projects --json` carries each board's `limits` too.
 
 `harbor premortem` runs a pre-mortem with your crew: `--start` asks everyone "it's after the end date and this project failed: what happened?", each person adds answers alone for five minutes, and then the answers show together on the project's Risks & issues tab, where each becomes a risk in one click. On its own it prints the question and the answers you can see. Once a project is Done, `harbor voyage` prints its voyage log (planned against actual dates, the biggest slips, the risks that came true, who closed the most, and the crew's lines) and adds yours. `harbor note` leaves a note for later on a project: it stays sealed (the crew sees only that it's there and who left it) until its day, until one of the program's milestones is reached, or until the project turns Off track, and then it opens at the top of the project and in the brief. `harbor sound TASK --ask crew` takes a sounding: it asks you, the task's owner and whoever has open work on its project how many working days the task will take (`--ask "Sam,Priya"` picks who). Each person answers alone with `harbor sound TASK 4 --why "…"`, and nobody sees the others' numbers until everyone has; then `harbor sound TASK` shows the spread, an estimate when the guesses are close, or "talk about this first" when they're far apart, and `--settle DAYS` records what you agreed. `harbor soundings` lists them, the ones waiting on your answer first.

package/dist/app.mjs

@@ -4126,7 +4126,7 @@ function roadmapWindow(zoom, today, shift = 0) {
 	};
 }
 /** Where a day falls in the window, 0–1, or null outside it. */
-function at(iso, w) {
+function at$1(iso, w) {
 	if (!iso) return null;
 	if (iso < w.start || iso >= w.end) return null;
 	return differenceInCalendarDays(day$2(iso), day$2(w.start)) / w.days;
@@ -4765,7 +4765,7 @@ function roadmapCells(start, end, milestones, w, width) {
 		if (s.clippedEnd) cells[b - 1] = "›";
 	}
 	for (const m of milestones) {
-		const pos = at(m.due, w);
+		const pos = at$1(m.due, w);
 		if (pos == null) continue;
 		cells[Math.min(width - 1, Math.floor(pos * width))] = m.done ? "◇" : "◆";
 	}
@@ -5726,7 +5726,7 @@ function programIsBlocked(data, program) {
 }
 function daysOverdue(dueDate, now) {
 	if (!dueDate) return 0;
-	const today = iso$2(now);
+	const today = iso$3(now);
 	if (today !== overdueDay) {
 		overdueDay = today;
 		overdueByDue.clear();
@@ -5745,7 +5745,7 @@ function daysOverdue(dueDate, now) {
 }
 function daysUntil$1(date, now) {
 	if (!date) return null;
-	const today = iso$2(now);
+	const today = iso$3(now);
 	if (today !== untilDay) {
 		untilDay = today;
 		untilByDate.clear();
@@ -5810,7 +5810,7 @@ function effectiveProjectHealth(project, data, now) {
 }
 /** Milestones past their date and still open. */
 function lateMilestonesOf(milestones, now) {
-	const today = iso$2(now);
+	const today = iso$3(now);
 	return milestones.filter((m) => !m.done && m.dueDate < today);
 }
 /**
@@ -5915,7 +5915,7 @@ function programLateCount(programId, data, now) {
 	for (const p of data.projects) if (p.programId === programId) late += lateTasksOf([...tasksOf(data.tasks, p.id)], now).length;
 	return late;
 }
-var iso$2, overdueDay, overdueByDue, untilDay, untilByDate;
+var iso$3, overdueDay, overdueByDue, untilDay, untilByDate;
 var init_derived_health = __esmMin((() => {
 	init_date_fns();
 	init_date_text();
@@ -5923,7 +5923,7 @@ var init_derived_health = __esmMin((() => {
 	init_indexes();
 	init_health_history();
 	init_clock();
-	iso$2 = (d) => {
+	iso$3 = (d) => {
 		return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, "0")}-${String(d.getDate()).padStart(2, "0")}`;
 	};
 	overdueDay = "";
@@ -8647,10 +8647,10 @@ function InboxView({ active, width, height, go }) {
 /** Open tasks for one person, bucketed by the week they are due, plus what is already late or has no date. */
 function weeklyLoad(tasks, personId, now, weeks = 6) {
 	const mine = tasks.filter((t) => t.assigneeId === personId && t.status !== "done");
-	const today = iso$1(now);
+	const today = iso$2(now);
 	const origin = startOfWeek(now, { weekStartsOn: 1 });
 	const buckets = Array.from({ length: weeks }, (_, i) => ({
-		start: iso$1(addDays(origin, i * 7)),
+		start: iso$2(addDays(origin, i * 7)),
 		due: 0
 	}));
 	let overdue = 0;
@@ -8674,10 +8674,10 @@ function weeklyLoad(tasks, personId, now, weeks = 6) {
 		weeks: buckets
 	};
 }
-var iso$1;
+var iso$2;
 var init_load = __esmMin((() => {
 	init_date_fns();
-	iso$1 = (d) => {
+	iso$2 = (d) => {
 		return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, "0")}-${String(d.getDate()).padStart(2, "0")}`;
 	};
 }));
@@ -11722,6 +11722,7 @@ init_format();
 const PAGES = {
 	today: "/today",
 	inbox: "/inbox",
+	week: "/week",
 	brief: "/brief",
 	review: "/review",
 	portfolios: "/portfolios",
@@ -17803,6 +17804,142 @@ var init_fog = __esmMin((() => {
 	fileCache = /* @__PURE__ */ new WeakMap();
 }));
 
+//#endregion
+//#region src/lib/passage.ts
+/** Hours as a person would say them: "2h", "1.5h", "30m". */
+function hoursText(h) {
+	if (h > 0 && h < 1) return `${Math.round(h * 60)}m`;
+	return `${Math.round(h * 10) / 10}h`;
+}
+/** Hours kept to the half hour, within what one day can take. */
+function clampHours(h) {
+	if (!Number.isFinite(h)) return 2;
+	return Math.min(12, Math.max(MIN_HOURS, Math.round(h * 2) / 2));
+}
+function dayHoursOf(person) {
+	const h = person?.dayHours;
+	return typeof h === "number" && h > 0 ? Math.min(16, h) : 7;
+}
+/** The Monday of the week a day falls in (a Saturday or Sunday looks ahead to the next week). */
+function weekOf(day = todayISO()) {
+	const d = at(day);
+	const wd = d.getDay();
+	const back = wd === 0 ? -1 : wd === 6 ? -2 : wd - 1;
+	return iso$1(addDays(d, -back));
+}
+/** Monday to Friday of the week starting `monday`. */
+function weekDays(monday) {
+	const d = at(monday);
+	return [
+		0,
+		1,
+		2,
+		3,
+		4
+	].map((i) => iso$1(addDays(d, i)));
+}
+function shiftWeek(monday, weeks) {
+	return iso$1(addDays(at(monday), weeks * 7));
+}
+/** One person's placements, every week. */
+function placementsOf(data, personId) {
+	return (data.reflections ?? []).filter((r) => isPassage(r) && r.authorId === personId);
+}
+/** The week as its owner plans it. Placements whose task is gone are left out. */
+function weekPlan(data, personId, monday) {
+	const tasks = byId(data.tasks);
+	const dates = weekDays(monday);
+	const dayHours = dayHoursOf(data.people.find((p) => p.id === personId));
+	const inWeek = placementsOf(data, personId).filter((r) => r.date && dates.includes(r.date) && r.taskId && tasks.has(r.taskId));
+	const days = dates.map((date) => {
+		const items = inWeek.filter((r) => r.date === date).sort((a, b) => a.createdAt.localeCompare(b.createdAt)).map((r) => ({
+			id: r.id,
+			task: tasks.get(r.taskId),
+			date,
+			hours: clampHours(r.hours ?? 2)
+		}));
+		const hours = items.reduce((sum, i) => sum + i.hours, 0);
+		return {
+			date,
+			items,
+			hours,
+			over: hours > dayHours
+		};
+	});
+	const placed = new Set(inWeek.map((r) => r.taskId));
+	const unplanned = data.tasks.filter((t) => t.assigneeId === personId && t.status !== "done" && !placed.has(t.id)).sort(byDue);
+	return {
+		monday,
+		days,
+		dayHours,
+		planned: days.reduce((sum, d) => sum + d.hours, 0),
+		capacity: dayHours * 5,
+		unplanned
+	};
+}
+/** Planned against done for a week: what was on the plan, what got finished, and what came in besides. */
+function weekReview(data, personId, monday) {
+	const plan = weekPlan(data, personId, monday);
+	const first = plan.days[0].date;
+	const sunday = iso$1(addDays(at(monday), 6));
+	const doneInWeek = (t) => t.status === "done" && Boolean(t.completedAt) && todayISO(new Date(t.completedAt)) >= first && todayISO(new Date(t.completedAt)) <= sunday;
+	const hoursBy = /* @__PURE__ */ new Map();
+	for (const d of plan.days) for (const i of d.items) {
+		const had = hoursBy.get(i.task.id);
+		hoursBy.set(i.task.id, {
+			task: i.task,
+			hours: (had?.hours ?? 0) + i.hours
+		});
+	}
+	const planned = [...hoursBy.values()].map(({ task, hours }) => ({
+		task,
+		hours,
+		done: task.status === "done" && (!task.completedAt || todayISO(new Date(task.completedAt)) <= sunday)
+	}));
+	const alsoDone = data.tasks.filter((t) => t.assigneeId === personId && doneInWeek(t) && !hoursBy.has(t.id)).sort((a, b) => (a.completedAt ?? "").localeCompare(b.completedAt ?? ""));
+	return {
+		monday,
+		planned,
+		doneCount: planned.filter((p) => p.done).length,
+		alsoDone,
+		plannedHours: plan.planned,
+		doneHours: planned.filter((p) => p.done).reduce((sum, p) => sum + p.hours, 0)
+	};
+}
+/** The one line the Friday view leads with. */
+function reviewText(r) {
+	if (r.planned.length === 0) return r.alsoDone.length ? `Nothing was planned, and you finished ${r.alsoDone.length}.` : "Nothing was planned this week.";
+	const also = r.alsoDone.length ? `, and ${r.alsoDone.length} more besides` : "";
+	return `You finished ${r.doneCount} of the ${r.planned.length} you planned${also}.`;
+}
+/** Placements of this person's from before the weeks kept, which a new plan clears. */
+function stalePlacements(data, personId, today = todayISO()) {
+	const cutoff = shiftWeek(weekOf(today), -12);
+	return new Set(placementsOf(data, personId).filter((r) => (r.date ?? "") < cutoff).map((r) => r.id));
+}
+var DAY_HOURS, DEFAULT_HOURS, MIN_HOURS, MAX_HOURS, isPassage, iso$1, at, byDue, DAY_WORDS;
+var init_passage = __esmMin((() => {
+	init_date_fns();
+	init_date_text();
+	init_format();
+	init_indexes();
+	DAY_HOURS = 7;
+	DEFAULT_HOURS = 2;
+	MIN_HOURS = .5;
+	MAX_HOURS = 12;
+	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);
+	DAY_WORDS = [
+		"mon",
+		"tue",
+		"wed",
+		"thu",
+		"fri"
+	];
+}));
+
 //#endregion
 //#region src/lib/mcp/tools.ts
 init_task_keys();
@@ -17823,6 +17960,7 @@ init_shipping_forecast();
 init_handover();
 init_work();
 init_fog();
+init_passage();
 init_board();
 init_soundings();
 /**
@@ -18037,6 +18175,44 @@ function taskLine(t, people, projects, all) {
 		...waitingOn ? { waitingOn } : {}
 	};
 }
+/** One person's week plan as the agent tools give it (get_week, plan_week). */
+function weekOut(data, personId, monday) {
+	const people = byId(data.people);
+	const projects = byId(data.projects);
+	const plan = weekPlan(data, personId, monday);
+	const review = weekReview(data, personId, monday);
+	return {
+		week: monday,
+		dayHours: plan.dayHours,
+		planned: plan.planned,
+		capacity: plan.capacity,
+		days: plan.days.map((d, i) => ({
+			date: d.date,
+			day: DAY_WORDS[i],
+			hours: d.hours,
+			...d.over ? {
+				over: true,
+				overBy: hoursText(d.hours - plan.dayHours)
+			} : {},
+			tasks: d.items.map((item) => ({
+				placement: item.id,
+				hours: item.hours,
+				...taskLine(item.task, people, projects, data.tasks)
+			}))
+		})),
+		unplanned: plan.unplanned.slice(0, 25).map((t) => taskLine(t, people, projects, data.tasks)),
+		unplannedCount: plan.unplanned.length,
+		review: {
+			summary: reviewText(review),
+			planned: review.planned.length,
+			done: review.doneCount,
+			plannedHours: review.plannedHours,
+			doneHours: review.doneHours,
+			stillOpen: review.planned.filter((p) => !p.done).map((p) => taskLine(p.task, people, projects, data.tasks)),
+			alsoDone: review.alsoDone.map((t) => taskLine(t, people, projects, data.tasks))
+		}
+	};
+}
 function raidScore(r) {
 	if (r.kind === "risk") return (r.probability ?? 3) * (r.impact ?? 3);
 	return (r.impact ?? 3) * 3;
@@ -18516,6 +18692,23 @@ const HARBOR_TOOLS = [
 			};
 		}
 	}),
+	tool({
+		name: "get_week",
+		title: "My week's plan",
+		description: "The person's own week plan (passage plan): their tasks laid on Monday to Friday with the hours each should take, against the hours they work a day (over: the day is fuller than that), the open tasks of theirs not yet on a day, and how the week went (planned against done, and what else they finished). Only ever the signed-in person's own; nobody else's plan can be read. week is any day in the week; it defaults to this one (a weekend looks at the next)." + DATA_NOTE,
+		input: object({
+			harbor: harborArg,
+			week: string().regex(/^\d{4}-\d{2}-\d{2}$/, "a date as YYYY-MM-DD").optional().describe("Any day in the week, YYYY-MM-DD.")
+		}),
+		run: (ctx, input) => {
+			const mine = me(ctx);
+			if (!mine) return {
+				you: null,
+				note: "You aren't one of this harbor's people yet, so there's no week to plan."
+			};
+			return weekOut(ctx.data, mine.id, weekOf(input.week ?? todayISO(ctx.now)));
+		}
+	}),
 	tool({
 		name: "weekly_brief",
 		title: "Weekly brief",
@@ -21228,6 +21421,60 @@ function milestonesRaidSlice({ set, get, write }) {
 				createdAt: stamp()
 			};
 			write({ reflections: [...all, row] });
+		},
+		planTask: (taskId, date, hours) => {
+			const s = get();
+			const me = s.currentUserId;
+			const task = s.tasks.find((t) => t.id === taskId);
+			if (!task || !/^\d{4}-\d{2}-\d{2}$/.test(date)) return null;
+			const all = s.reflections ?? [];
+			const same = all.find((r) => isPassage(r) && r.authorId === me && r.taskId === taskId && r.date === date);
+			if (same) {
+				if (hours !== void 0) get().setPlacementHours(same.id, hours);
+				return same.id;
+			}
+			const stale = stalePlacements(s, me, date < todayISO() ? date : todayISO());
+			const row = {
+				id: uid("rf"),
+				projectId: task.projectId,
+				kind: "passage",
+				authorId: me,
+				body: "",
+				createdAt: stamp(),
+				taskId,
+				date,
+				hours: clampHours(hours ?? 2)
+			};
+			write({ reflections: [...all.filter((r) => !stale.has(r.id)), row] });
+			return row.id;
+		},
+		movePlacement: (id, date) => {
+			const me = get().currentUserId;
+			const all = get().reflections ?? [];
+			const row = all.find((r) => r.id === id && isPassage(r) && r.authorId === me);
+			if (!row || row.date === date || !/^\d{4}-\d{2}-\d{2}$/.test(date)) return;
+			const there = all.find((r) => isPassage(r) && r.authorId === me && r.taskId === row.taskId && r.date === date);
+			write({ reflections: there ? all.filter((r) => r.id !== id).map((r) => r.id === there.id ? {
+				...r,
+				hours: clampHours((r.hours ?? 0) + (row.hours ?? 0))
+			} : r) : all.map((r) => r.id === id ? {
+				...r,
+				date
+			} : r) });
+		},
+		setPlacementHours: (id, hours) => {
+			const me = get().currentUserId;
+			const h = clampHours(hours);
+			write({ reflections: (get().reflections ?? []).map((r) => r.id === id && isPassage(r) && r.authorId === me && r.hours !== h ? {
+				...r,
+				hours: h
+			} : r) });
+		},
+		unplan: (id) => {
+			const me = get().currentUserId;
+			const all = get().reflections ?? [];
+			if (!all.some((r) => r.id === id && isPassage(r) && r.authorId === me)) return;
+			write({ reflections: all.filter((r) => r.id !== id) });
 		}
 	};
 }
@@ -21238,6 +21485,8 @@ var init_milestones_raid = __esmMin((() => {
 	init_raid();
 	init_decisions();
 	init_raid_history();
+	init_passage();
+	init_format();
 	init_utils();
 	init_shared();
 }));

package/lib/cli.mjs

@@ -51,6 +51,7 @@ import {
   taskLine,
   taskList,
   todayLocal,
+  weekText,
 } from "./format.mjs";
 import { colourDepth, logoLines } from "./logo.mjs";
 import { HarborError, createClient } from "./mcp.mjs";
@@ -136,7 +137,9 @@ export const HELP = `harbor: Harbor from the terminal
                                               project as that one really ran
   harbor add "TITLE" --project P [--assignee me|none|NAME] [--due DATE]
                      [--priority low|medium|high|urgent] [--status S]
-                     [--over-limit]
+                     [--comment TEXT] [--over-limit]
+                                              with no TITLE: one title a line
+                                              from stdin
   harbor start TASK | submit TASK | done TASK [--confirm] [--over-limit]
                                               move a task to In play, In review
                                               or Done
@@ -146,6 +149,13 @@ export const HELP = `harbor: Harbor from the terminal
                    [--waits-on TASK,TASK|none] [--confirm] [--over-limit]
   harbor limit PROJECT [COLUMN N|none]        how many tasks a board column
                                               takes at once; the owner sets it
+  harbor week [--next|--last|--week DATE] [--review]
+                                              your own week: tasks on days
+                                              against your hours, only for
+                                              you; --review: planned vs done
+  harbor week TASK DAY [--hours N]            put a task on a day: mon to fri
+  harbor week TASK --off [DAY]                take it off that day, or the week
+  harbor week --day-hours N                   the hours you work a day
   harbor comment TASK "TEXT"
   harbor checkin "WHAT YOU'RE DOING" [--on-blocker]
   harbor risk "TITLE" --project P|--program P [--impact 1-5] [--probability 1-5]
@@ -333,6 +343,13 @@ export function localMinute(now = new Date()) {
   return `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}T${pad(now.getHours())}:${pad(now.getMinutes())}`;
 }
 
+/** All of a stream's text: titles piped to harbor add. */
+async function readAll(stream) {
+  let text = "";
+  for await (const chunk of stream) text += chunk;
+  return text;
+}
+
 const one = (positionals, what) => {
   if (positionals.length !== 1) throw new HarborError(`Give one ${what}.`);
   return positionals[0];
@@ -1951,24 +1968,61 @@ export async function run(argv, io = {}) {
     }
     case "add": {
       const { positionals, values, harbor } = parse(
-        spec(["over-limit"], ["project", "assignee", "due", "priority", "status"]),
+        spec(["over-limit"], ["project", "assignee", "due", "priority", "status", "comment"]),
       );
       if (!values.project) throw new HarborError("Say which project: --project NAME.");
-      return call(
-        "create_task",
-        {
+      // Several at once: one title a line on stdin, with no title (or -) after add.
+      const piped = positionals.length === 0 || (positionals.length === 1 && positionals[0] === "-");
+      const stdin = io.stdin ?? process.stdin;
+      const titles =
+        piped && (io.stdin || !process.stdin.isTTY)
+          ? (await readAll(stdin))
+              .split(/\r?\n/)
+              .map((l) => l.trim())
+              .filter(Boolean)
+          : [text(positionals, "the task")];
+      if (titles.length === 0) throw new HarborError("Say the task, or give one title a line on stdin.");
+      if (titles.length > 100) throw new HarborError("That's more than 100 tasks; harbor import FILE takes a spreadsheet.");
+      const added = [];
+      for (const title of titles) {
+        const r = await client.call("create_task", {
           harbor,
           project: values.project,
-          title: text(positionals, "the task"),
+          title,
           // Yours unless you say otherwise, as with n in the app.
           assignee: values.assignee ?? "me",
           due: dueDate(values.due),
           priority: values.priority,
           status: values.status === undefined ? undefined : statusWord(values.status),
           overLimit: values["over-limit"] || undefined,
-        },
-        (r) => `Added: ${taskLine(r.created, opts)}`,
-      );
+        }).catch((err) => {
+          if (err instanceof HarborError) {
+            const done = added.length ? ` (added ${added.length} before it)` : "";
+            throw new HarborError(`${hint(err.message, values.project)}${done}`);
+          }
+          throw err;
+        });
+        if (values.comment)
+          r.comment = (
+            await client.call("add_comment", {
+              harbor,
+              task: r.created.key ?? r.created.id,
+              body: values.comment,
+            })
+          ).commented;
+        added.push(r);
+      }
+      await stalePromptCache(env);
+      if (asJson) out(jsonText(added.length === 1 ? added[0] : { added }));
+      else
+        out(
+          plain(
+            added
+              .map((r) => `Added: ${taskLine(r.created, opts)}${r.comment ? ", with your comment" : ""}`)
+              .join("\n"),
+          ),
+        );
+      return 0;
     }
     case "start":
     case "submit":
@@ -2072,6 +2126,46 @@ export async function run(argv, io = {}) {
             .join("\n"),
       );
     }
+    case "week": {
+      const { positionals, values, harbor } = parse(
+        spec(["next", "last", "review", "off"], ["week", "hours", "day-hours"]),
+      );
+      if ([values.next, values.last, values.week].filter(Boolean).length > 1)
+        throw new HarborError("Say one of --next, --last or --week DATE.");
+      const base = values.week ? dueDate(values.week) : opts.today;
+      const shift = values.next ? 7 : values.last ? -7 : 0;
+      const at = new Date(`${base}T12:00:00`);
+      const week = todayLocal(new Date(at.getFullYear(), at.getMonth(), at.getDate() + shift));
+      const number = (v, name) => {
+        if (v === undefined) return undefined;
+        const n = Number(v);
+        if (!Number.isFinite(n) || n <= 0) throw new HarborError(`--${name} is a number of hours, like 2 or 1.5.`);
+        return n;
+      };
+      const [task, day, ...extra] = positionals;
+      if (extra.length) throw new HarborError("Give a task key and a day: harbor week RR-42 wed.");
+      const dayHours = number(values["day-hours"], "day-hours");
+      const show = (r) => [r.done, weekText(r, { ...opts, review: Boolean(values.review) })].filter(Boolean).join("\n\n");
+      if (!task && dayHours === undefined) {
+        if (values.off || values.hours) throw new HarborError("Say which task: harbor week RR-42 wed --hours 3.");
+        return call("get_week", { harbor, week }, show);
+      }
+      if (task && !day && !values.off)
+        throw new HarborError(`Say which day for ${task}: harbor week ${task} wed, or --off to take it off the week.`);
+      return call(
+        "plan_week",
+        {
+          harbor,
+          week,
+          ...(task ? { task } : {}),
+          ...(day ? { day } : {}),
+          ...(values.hours ? { hours: number(values.hours, "hours") } : {}),
+          ...(values.off ? { remove: true } : {}),
+          ...(dayHours !== undefined ? { dayHours } : {}),
+        },
+        show,
+      );
+    }
     case "comment": {
       const { positionals, harbor } = parse(spec());
       const [task, ...words] = positionals;

package/lib/format.mjs

@@ -856,6 +856,56 @@ export function exportData(r) {
   };
 }
 
+const DAY_NAME = { mon: "Mon", tue: "Tue", wed: "Wed", thu: "Thu", fri: "Fri" };
+const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
+const hours = (h) => (h > 0 && h < 1 ? `${Math.round(h * 60)}m` : `${Math.round(h * 10) / 10}h`);
+const monthDay = (iso) => `${MONTHS[Number(iso.slice(5, 7)) - 1]} ${Number(iso.slice(8, 10))}`;
+
+/** get_week as the terminal shows it: the five days with their hours, what's not on a day yet, and how it went. */
+export function weekText(w, { today, review = false, width } = {}) {
+  if (!w.days) return w.note ?? "No week to show.";
+  const first = w.days[0].date;
+  const last = w.days[4].date;
+  const out = [
+    `Your week · ${monthDay(first)} to ${monthDay(last)} · ${hours(w.planned)} of ${hours(w.capacity)} planned (only you see it)`,
+  ];
+  const reviewing = review || (today && today >= last);
+  if (!review) {
+    for (const d of w.days) {
+      const head = `${DAY_NAME[d.day]} ${Number(d.date.slice(8, 10))}`;
+      const load = d.tasks.length ? `${hours(d.hours)} of ${hours(w.dayHours)}` : "nothing planned";
+      out.push(
+        "",
+        `${head}  ${load}${d.over ? ` · too full by ${d.overBy}` : ""}${d.date === today ? " · today" : ""}`,
+      );
+      for (const t of d.tasks) {
+        const tail = `  ${hours(t.hours)}${t.status === "done" ? " · done" : ""}`;
+        const key = `  ${t.key ?? t.id}  `;
+        out.push(
+          key + fitTitle(t.title, width ? width - 1 - key.length - tail.length : Infinity) + tail,
+        );
+      }
+    }
+    if (w.unplannedCount) {
+      out.push("", `Not on a day yet: ${w.unplannedCount}. harbor week KEY DAY puts one there.`);
+      for (const t of w.unplanned.slice(0, 5))
+        out.push(`  ${taskLine(t, { today, mine: true, width: width ? width - 2 : undefined })}`);
+      if (w.unplannedCount > 5) out.push(`  … and ${w.unplannedCount - 5} more (--json lists 25)`);
+    }
+  }
+  if (reviewing) {
+    const r = w.review;
+    out.push("", `How it went: ${r.summary}`);
+    if (r.planned)
+      out.push(`  ${hours(r.doneHours)} of the ${hours(r.plannedHours)} planned is done.`);
+    if (review) {
+      for (const t of r.stillOpen) out.push(`  open  ${taskLine(t, { today, mine: true })}`);
+      for (const t of r.alsoDone) out.push(`  also  ${taskLine(t, { today, mine: true })}`);
+    }
+  }
+  return out.join("\n");
+}
+
 /** fog: the open tasks nobody has touched for three weeks, longest first. */
 export function fogText(r, { sweepHint = true } = {}) {
   const where = r.project ? ` in ${r.project}` : "";

package/package.json

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