@harborppm/cli 0.41.0 → 0.43.0

package/README.md

@@ -83,7 +83,7 @@ waits: [CS-2]
 Old endpoints go away on Nov 20.
 ```
 
-A new file with any name is a new task: `harbor sync` adds it and renames it to its key. A field changed in a file and not on the website goes to Harbor; one changed in both places keeps the website's and says so. Removing a file doesn't delete the task (mark it done instead). On a fresh clone, run `harbor sync` before editing. `harbor init --hook` adds a git post-commit hook that syncs after each commit.
+A new file with any name is a new task: `harbor sync` adds it and renames it to its key. A field changed in a file and not on the website goes to Harbor; one changed in both places keeps the website's and says so. Removing a file doesn't delete the task (mark it done instead). On a fresh clone, run `harbor sync` before editing. `harbor init --hook` adds a git post-commit hook that syncs after each commit, and `--dry-run` on either says what it would do without writing or sending anything.
 
 No account? `harbor init --local` makes a plan that lives only in the folder (the rest of it in `.harbor/plan.json`), and `harbor` in that folder opens it full screen, offline and free. Later, `harbor init PROJECT` moves its tasks into a project on harborppm.com.
 
@@ -161,9 +161,9 @@ harbor premortem PROJECT ["WHAT WENT WRONG"] [--start]
 harbor voyage PROJECT ["YOUR LINE"]
 harbor note PROJECT ["NOTE"] [--opens DATE|--milestone NAME|--off-track]
 harbor limit PROJECT [COLUMN N|none]
-harbor init [PROJECT] [--hook]              a project's tasks as files in this repository
+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]                       the files and the website, in step both ways
+harbor sync [--quiet] [--dry-run]           the files and the website, in step both ways
 harbor handover PERSON [--to NAME] [--until DATE] [--note TEXT] [--keep ID,ID] [--confirm]
 harbor handback PERSON
 harbor agent [--agent NAME]

package/dist/app.mjs

@@ -3009,10 +3009,18 @@ function tideForecast(project, tasks, now) {
 		remaining
 	};
 	const today = todayISO(now);
-	const runs = simulate(remaining, weekly, hash(`${project.id}|${remaining}|${today}`));
 	const base = noon(today);
+	const paced = simulate(remaining, weekly, hash(`${project.id}|${remaining}|${today}`));
+	const at = (share, list = runs) => list[Math.min(list.length - 1, Math.ceil(share * list.length) - 1)];
+	let lastDue = null;
+	for (const t of tasks) {
+		if (t.status === "done" || !t.dueDate) continue;
+		if (!lastDue || t.dueDate > lastDue.dueDate) lastDue = t;
+	}
+	const floor = lastDue ? differenceInCalendarDays(noon(lastDue.dueDate), base) : 0;
+	const runs = floor > 0 ? paced.map((d) => Math.max(d, floor)) : paced;
+	const heldBy = lastDue && floor > at(.5, paced) ? lastDue : null;
 	const dayOf = (days) => Number.isFinite(days) ? todayISO(addDays(base, days)) : null;
-	const at = (share) => runs[Math.min(runs.length - 1, Math.ceil(share * runs.length) - 1)];
 	const toEnd = differenceInCalendarDays(noon(project.endDate), base);
 	const byEnd = runs.filter((d) => d <= toEnd).length / runs.length;
 	const last = Math.max(Number.isFinite(at(.99)) ? at(.99) : 728, toEnd + 14, 7);
@@ -3037,7 +3045,8 @@ function tideForecast(project, tasks, now) {
 		almostCertain: dayOf(at(.95)),
 		chanceByEnd: Math.round(byEnd * 100) / 100,
 		curve,
-		rough: finished < ROUGH_BELOW
+		rough: finished < ROUGH_BELOW,
+		heldBy
 	};
 }
 /** "15%", with "under 5%" and "over 95%" at the ends, where a thousand runs can't be that sure. */
@@ -3046,6 +3055,13 @@ function chanceText(chance) {
 	if (chance > .95) return "over 95%";
 	return `${Math.round(chance * 20) * 5}%`;
 }
+/**
+* The open task whose due date sets the finish, when the crew's pace alone
+* would be done sooner; null otherwise.
+*/
+function dueAfterFinish(tide) {
+	return tide.kind === "forecast" ? tide.heldBy : null;
+}
 
 //#endregion
 //#region src/lib/flow.ts
@@ -3956,11 +3972,13 @@ function filterTasks(tasks, f) {
 }
 /**
 * When the project will likely finish at its crew's recent pace, in one
-* line under its name, and whether that misses the end date. Empty when
+* line under its name, whether that misses the end date, and the open task
+* whose due date holds it later than the pace would. Empty when
 * there's no forecast (all done, paused, or nothing finished lately).
 */
 function tideLine(data, project, today) {
-	const tide = tideForecast(project, tasksOf(data.tasks, project.id), parseIso(`${today}T12:00:00`));
+	const tasks = tasksOf(data.tasks, project.id);
+	const tide = tideForecast(project, tasks, parseIso(`${today}T12:00:00`));
 	if (tide.kind === "no-pace") return {
 		text: "No forecast yet: nothing finished in the last few weeks",
 		late: false
@@ -3972,8 +3990,10 @@ function tideLine(data, project, today) {
 	};
 	const very = tide.veryLikely ? `, very likely by ${shortDay(tide.veryLikely, today)}` : "";
 	const end = project.endDate >= today ? ` · ${chanceText(tide.chanceByEnd)} by its end, ${shortDay(project.endDate, today)}` : "";
+	const later = dueAfterFinish(tide);
+	const due = later ? ` · ${taskKey(later, project) ?? `“${later.title}”`} is due ${shortDay(later.dueDate.slice(0, 10), today)}` : "";
 	return {
-		text: `Probably done ${shortDay(tide.likely, today)}${very}${end}${tide.rough ? " · rough" : ""}`,
+		text: `Probably done ${shortDay(tide.likely, today)}${very}${end}${due}${tide.rough ? " · rough" : ""}`,
 		late: tide.chanceByEnd < .5
 	};
 }
@@ -15529,12 +15549,33 @@ async function saveOrStop(sync) {
 	await sync.flush();
 	if (sync.state !== "saved") throw new HarborError(sync.state === "offline" ? "Can't reach Harbor, so nothing was sent and the folder was left as it was." : "Harbor didn't take the changes, so the folder was left as it was. Try harbor sync again.");
 }
-/** `harbor sync` on a linked plan. */
+/**
+* A --dry-run's folder and transport: everything is read as usual, and
+* nothing is written to disk or sent to Harbor.
+*/
+function dry(folder, transport) {
+	return {
+		folder: {
+			...folder,
+			write: async () => {},
+			remove: async () => {}
+		},
+		transport: {
+			...transport,
+			save: () => new Promise(() => {})
+		}
+	};
+}
+/** `harbor sync` on a linked plan; with dryRun, only what it would do. */
 async function syncLinked(opts) {
-	const { folder, config, say } = opts;
+	const { config, say } = opts;
+	const { folder, transport } = opts.dryRun ? dry(opts.folder, opts.transport) : {
+		folder: opts.folder,
+		transport: opts.transport
+	};
 	if (!config.harbor) throw new HarborError("This plan isn't linked to a harbor.");
-	const { account } = await opts.transport.harbors();
-	const { store, sync } = await openHarbor(opts.transport, account, config.harbor.id, say);
+	const { account } = await transport.harbors();
+	const { store, sync } = await openHarbor(transport, account, config.harbor.id, say);
 	try {
 		const projectId = config.project.id;
 		if (!store.getState().projects.some((p) => p.id === projectId)) throw new HarborError(`${config.project.name} isn't in ${config.harbor.name} any more. Run harbor init PROJECT to link another.`);
@@ -15544,7 +15585,7 @@ async function syncLinked(opts) {
 			say
 		});
 		if (done.report.sent.length + done.report.added.length > 0 && readOnlyHarbor(store.getState())) throw new HarborError(store.getState().keepPaused ? "This harbor's free trial has ended, so the folder's changes weren't sent. Its owner can subscribe at harborppm.com/keep." : "You can only view this harbor, so the folder's changes weren't sent. The folder was left as it was.");
-		await saveOrStop(sync);
+		if (!opts.dryRun) await saveOrStop(sync);
 		const project = store.getState().projects.find((p) => p.id === projectId);
 		if (project.key && project.key !== config.project.key) await folder.write(CONFIG_FILE, json({
 			...config,
@@ -15579,18 +15620,22 @@ function projectNamed(projects, text, opts = {}) {
 * A local plan here moves its tasks into the project first.
 */
 async function initLinked(opts) {
-	const { folder, say } = opts;
+	const { say } = opts;
+	const { folder, transport } = opts.dryRun ? dry(opts.folder, opts.transport) : {
+		folder: opts.folder,
+		transport: opts.transport
+	};
 	const existing = await readConfig(folder);
 	if (existing && !existing.local) throw new HarborError(`This folder already follows ${existing.project.name}. Run harbor sync to bring it up to date.`);
-	const answer = await opts.transport.harbors();
+	const answer = await transport.harbors();
 	if (answer.harbors.length === 0) throw new HarborError("You're not in a harbor yet. Run harbor to make one first.");
 	const harbor = opts.pickHarbor(answer.harbors);
-	const { store, sync } = await openHarbor(opts.transport, answer.account, harbor.id, say);
+	const { store, sync } = await openHarbor(transport, answer.account, harbor.id, say);
 	try {
 		const project = projectNamed(store.getState().projects, opts.project, { exactOnly: opts.exactOnly });
 		let moved = 0;
 		if (existing?.local) moved = await moveLocalTasks(folder, store, project.id, say);
-		await saveOrStop(sync);
+		if (!opts.dryRun) await saveOrStop(sync);
 		const settled = store.getState().projects.find((p) => p.id === project.id);
 		const config = {
 			version: 1,
@@ -15614,9 +15659,12 @@ async function initLinked(opts) {
 			consumed: /* @__PURE__ */ new Set(),
 			skipped: /* @__PURE__ */ new Set()
 		}, report, true);
+		const mine = data.tasks.filter((t) => t.projectId === project.id);
+		const open = mine.filter((t) => t.status !== "done").length;
 		return {
 			config,
-			tasks: data.tasks.filter((t) => t.projectId === project.id).length,
+			tasks: mine.length,
+			open,
 			moved,
 			report
 		};
@@ -15853,13 +15901,14 @@ var commands_exports = /* @__PURE__ */ __exportAll({
 	syncHere: () => syncHere,
 	syncLine: () => syncLine
 });
-/** The one line a sync ends with. */
-function syncLine(report) {
+/** The one line a sync ends with; a dry run's says what it would have done. */
+function syncLine(report, dryRun = false) {
 	const parts = [
-		report.sent.length ? `sent ${plural(report.sent.length, "change")} to Harbor` : "",
-		report.added.length ? `added ${plural(report.added.length, "task")}` : "",
-		report.took.length ? `brought in ${plural(report.took.length, "change")} from Harbor` : ""
+		report.sent.length ? `${dryRun ? "would send" : "sent"} ${plural(report.sent.length, "change")} to Harbor` : "",
+		report.added.length ? `${dryRun ? "would add" : "added"} ${plural(report.added.length, "task")}` : "",
+		report.took.length ? `${dryRun ? "would bring in" : "brought in"} ${plural(report.took.length, "change")} from Harbor` : ""
 	].filter(Boolean);
+	if (dryRun) return `⚓ Dry run: ${parts.length ? parts.join(", ") : "already in step with Harbor"}. Nothing was written or sent.`;
 	return parts.length ? `⚓ ${parts.join(", ")}.` : "⚓ Already in step with Harbor.";
 }
 /** The local plan above `cwd`, if that's what's there. */
@@ -15908,22 +15957,29 @@ async function initHere(opts) {
 		project: opts.project?.trim() || basename(home),
 		exactOnly: !opts.project?.trim(),
 		pickHarbor: opts.pickHarbor,
-		say: opts.say
+		say: opts.say,
+		dryRun: opts.dryRun
 	});
 	const { project, harbor } = made.config;
-	opts.say(made.moved ? `Moved this folder's ${plural(made.moved, "task")} into ${project.name} in ${harbor.name}.` : `Made ${shownDir(opts.cwd, dir)} for ${project.name} (${project.key}) in ${harbor.name}, with ${plural(made.tasks, "task")}. Commit it like any code.`);
+	const counted = made.open === made.tasks ? plural(made.tasks, "task") : `${made.open} open and ${made.tasks - made.open} done ${made.tasks === 1 ? "task" : "tasks"}`;
+	if (opts.dryRun) {
+		opts.say(made.moved ? `Would move this folder's ${plural(made.moved, "task")} into ${project.name} (${project.key}) in ${harbor.name}.` : `Would make ${shownDir(opts.cwd, dir)} for ${project.name} (${project.key}) in ${harbor.name}, with a file for each of its ${counted}.`);
+		opts.say("Dry run: nothing was written or sent. Run it again without --dry-run to do it.");
+		return made.config;
+	}
+	opts.say(made.moved ? `Moved this folder's ${plural(made.moved, "task")} into ${project.name} in ${harbor.name}.` : `Made ${shownDir(opts.cwd, dir)} for ${project.name} (${project.key}) in ${harbor.name}, with a file for each of its ${counted}. Commit it like any code.`);
 	opts.say("Edit a file, or add one, then run harbor sync. Changes on the website come back the same way.");
 	if (opts.hook) opts.say(await addHook(home));
 	return made.config;
 }
-/** `harbor sync`: the plan above `cwd` and its project, both ways. */
+/** `harbor sync`: the plan above `cwd` and its project, both ways; with dryRun, what it would do. */
 async function syncHere(opts) {
 	const dir = await findPlan(opts.cwd);
 	if (!dir) throw new HarborError("There's no plan here. Run harbor init PROJECT in your repository to make one.");
 	const folder = diskFolder(dir);
 	const config = await readConfig(folder);
 	if (config.local) {
-		await loadLocal(folder, opts.say);
+		if (!opts.dryRun) await loadLocal(folder, opts.say);
 		opts.say("⚓ This plan lives only in this folder, so there's nothing to sync with. harbor init PROJECT keeps it in step with a project on harborppm.com.");
 		return null;
 	}
@@ -15931,10 +15987,11 @@ async function syncHere(opts) {
 		transport: await opts.transport(),
 		folder,
 		config,
-		say: opts.say
+		say: opts.say,
+		dryRun: opts.dryRun
 	});
 	for (const c of report.clashes) opts.say(c);
-	opts.say(syncLine(report));
+	opts.say(syncLine(report, opts.dryRun));
 	return report;
 }
 /** A post-commit hook that syncs after each commit; an existing hook is only added to. */

package/lib/cli.mjs

@@ -22,8 +22,11 @@ import {
   forecastList,
   forecastOne,
   STATUS,
+  statusWord,
+  exportData,
   harbors,
   whoami,
+  whoamiData,
   limitsText,
   hillData,
   hillList,
@@ -94,13 +97,14 @@ export const HELP = `harbor: Harbor from the terminal
                                               a project's public roadmap: read,
                                               publish or take it down
 
-  harbor init [PROJECT] [--hook]              keep a project's tasks as files in
+  harbor init [PROJECT] [--hook] [--dry-run]  keep a project's tasks as files in
                                               this repository (.harbor/), one
                                               per task, in step both ways
   harbor init --local [NAME]                  a plan in this folder alone, no
                                               account; harbor here opens it
-  harbor sync [--quiet]                       send the files' edits to Harbor
+  harbor sync [--quiet] [--dry-run]           send the files' edits to Harbor
                                               and bring its changes back
+                                              (--dry-run: only say what)
 
   harbor program "NAME" [--portfolio P] [--lead me|NAME] [--starts DATE]
                        [--ends DATE]
@@ -153,11 +157,12 @@ export const HELP = `harbor: Harbor from the terminal
                                               the crew, in the order to do them
   harbor agent report TASK "WHAT YOU DID" [--start] [--agent NAME]
                                               the agent's note; moves the task
-                                              to In review (--start: doing)
+                                              to In review (--start: In play)
 
   Every command takes --json, and --harbor NAME when you're in more than one
   harbor (or set one with harbor use). harbor help COMMAND shows just that one.
-  Statuses: backlog, todo, doing, review, done.
+  Statuses: backlog, todo, doing, review, done (the board's words work too:
+  "to do", "in play"; --json says doing for In play).
   DATE: YYYY-MM-DD, today, tomorrow, or +N for N days from today.
   Changes show in Harbor's History as yours, "via Harbor CLI". These commands
   never delete; the full-screen app can, as the website can, and asks first.
@@ -417,10 +422,17 @@ const DETAIL = {
     "                                         repository, one file per task in",
     "                                         PROJECT (a key like RR or a name;",
     "                                         the folder's name when left out)",
+    "  harbor init [PROJECT] --dry-run        reads: says which project and how",
+    "                                         many tasks, and writes nothing",
     "  harbor init --local [NAME]             writes: a plan that lives only in",
     "                                         this folder, with no account;",
     "                                         harbor here opens it full screen",
     "",
+    "  .harbor/ goes at the top of the git repository you're in; outside one, in",
+    "  this folder. Without PROJECT, only a project called exactly what the",
+    "  folder is will do: when none is, nothing is made and Harbor lists the",
+    "  projects there are, with their keys, to name one.",
+    "",
     "  Each file has title, status, owner, due, priority and waits between --- lines,",
     "  and the task's notes below. Edit them, add new ones (any name; Harbor gives",
     "  them a key), review them in pull requests, then run harbor sync. --hook adds",
@@ -430,11 +442,14 @@ const DETAIL = {
   sync: [
     "  harbor sync [--quiet]                  writes: sends what the files changed to",
     "                                         Harbor and rewrites the files from it",
+    "  harbor sync --dry-run                  reads: says what it would send and",
+    "                                         bring in, and changes nothing",
     "",
     "  A field you changed and nobody changed on the website goes to Harbor; one",
     "  changed in both places keeps the website's, and says so. Removing a file",
     "  doesn't delete the task (mark it done instead). On a fresh clone, run",
-    "  harbor sync before editing. --quiet prints only problems.",
+    "  harbor sync before editing. --quiet prints only problems. It works from",
+    "  anywhere inside the folder that holds .harbor/.",
   ],
   limit: [
     "  harbor limit PROJECT                   reads its board's column limits",
@@ -443,7 +458,8 @@ const DETAIL = {
     "                                         1-5, 8, 10 and 15)",
     "  harbor limit PROJECT COLUMN none       writes: no limit on COLUMN",
     "",
-    "  COLUMN is a status: doing or review usually, or backlog, todo, done.",
+    "  COLUMN is a status: doing (In play) or review usually, or backlog, todo,",
+    "  done.",
     "  Only the harbor's owner can change a limit. A move past a limit is",
     "  refused until you run it again with --over-limit.",
   ],
@@ -467,12 +483,14 @@ const DETAIL = {
     "  harbor roadmap PROJECT --publish --dates",
     "                                         writes: also shows the day each thing",
     "                                         shipped (--no-dates: titles only, the",
-    "                                         default)",
+    "                                         first time's default; without either,",
+    "                                         it stays as it is)",
     "  harbor roadmap PROJECT --publish --site",
     "                                         writes: also shows it at",
     "                                         harborppm.com/roadmap, in place of any",
     "                                         other (Harbor's own team only;",
-    "                                         --no-site, the default, takes it off)",
+    "                                         --no-site takes it off; without",
+    "                                         either, it stays as it is)",
     "  harbor roadmap PROJECT --off           writes: takes it down at once; the link",
     "                                         then says it isn't published, and",
     "                                         publishing again makes a new link",
@@ -488,12 +506,13 @@ const DETAIL = {
     "  harbor forecast PROJECT                reads one project's forecast and what",
     "                                         it rests on",
     "",
-    "  Worked out from the crew's pace alone: how many tasks they finished each",
-    "  week over the last six (or the project's life, if shorter), replayed a",
+    "  Worked out from the crew's pace: how many tasks they finished each week",
+    "  over the last six (or the project's life, if shorter), replayed a",
     "  thousand times until its open tasks run out. Probably is half of those",
     "  runs, very likely 85%, almost certainly 95%. No estimates or points.",
-    "  It warns when under two weeks of pace is all there is, and when an open",
-    "  task is due after the likely finish, since the pace can't see due dates.",
+    "  No run finishes before the last open task is due, so a task due later",
+    "  than the pace would finish sets the dates, and the forecast names it. It",
+    "  warns when under two weeks of pace is all there is.",
   ],
   report: [
     "  harbor report PROGRAM                  reads the program's status report",
@@ -509,7 +528,9 @@ const DETAIL = {
     "  harbor export review                   reads the review as CSV",
     "",
     "  The same spreadsheets the website's Export buttons download. They print;",
-    "  harbor export tasks RR > tasks.csv saves one.",
+    "  harbor export tasks RR > tasks.csv saves one. A task export starts with",
+    "  each task's key, so harbor import matches those tasks by key. With",
+    "  --json, rows is one object per row, keyed by column.",
   ],
   import: [
     "  harbor import FILE --project P         writes: adds the file's tasks",
@@ -519,7 +540,8 @@ const DETAIL = {
     "  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",
     "  there. People it names who aren't in the harbor are added unless you say",
-    "  --no-people. A task already in its project by title is left alone.",
+    "  --no-people. A task already in its project is left alone: by its key",
+    "  (a Key column, as harbor export writes) or by title.",
   ],
   note: [
     "  harbor note PROJECT                    reads its notes for later: who left",
@@ -564,14 +586,17 @@ const DETAIL = {
   agent: [
     "  harbor agent                           reads the tasks people gave the crew's",
     "                                         agent (an AI crew member on People),",
-    "                                         in progress first, with their notes",
+    "                                         in play first, with their notes",
     '  harbor agent report TASK "TEXT"        writes: the agent\'s note on the task,',
     "                                         and moves it to In review for a person",
     "                                         to check",
     '  harbor agent report TASK "TEXT" --start',
     "                                         writes: the note, and moves it to",
-    "                                         In progress",
+    "                                         In play",
     "",
+    "  TASK is a task key, like RR-42 (harbor agent lists them), or an id. It",
+    "  has to be assigned to an agent: for anyone else's task, report refuses",
+    "  and nothing changes, so assign it to the agent on the website first.",
     "  --agent NAME picks the agent when the crew has more than one. An agent",
     "  never marks its own work Done; a person does, on the website or in the",
     "  terminal app.",
@@ -976,7 +1001,7 @@ export async function run(argv, io = {}) {
   if (command === "init" || command === "sync") {
     const init = command === "init";
     const { values, positionals } = parseArgs(rest, {
-      flags: init ? ["local", "hook", "json"] : ["quiet", "json"],
+      flags: init ? ["local", "hook", "json", "dry-run"] : ["quiet", "json", "dry-run"],
       options: init ? ["harbor"] : [],
     });
     const cwd = io.cwd ?? process.cwd();
@@ -989,7 +1014,12 @@ export async function run(argv, io = {}) {
           }
         : (line) => out(plain(line));
     const app = await loadApp();
+    const dryRun = Boolean(values["dry-run"]);
     if (init && values.local) {
+      if (dryRun)
+        throw new HarborError(
+          "harbor init --local only writes files in this folder, with no account; leave out --dry-run.",
+        );
       if (positionals.length > 1)
         throw new HarborError(`harbor init --local takes one name; put it in quotes.`);
       const config = await app.initLocalHere({ cwd, name: positionals[0], say });
@@ -1023,6 +1053,7 @@ export async function run(argv, io = {}) {
         transport: await transport(),
         project: positionals[0],
         hook: Boolean(values.hook),
+        dryRun,
         say,
         pickHarbor: (list) => {
           if (values.harbor) return app.harborNamed(list, values.harbor);
@@ -1034,11 +1065,14 @@ export async function run(argv, io = {}) {
           );
         },
       });
-      if (values.json) out(jsonText({ plan: config, notes: lines }));
+      if (values.json) out(jsonText({ plan: config, ...(dryRun ? { dryRun } : {}), notes: lines }));
       return 0;
     }
-    const report = await app.syncHere({ cwd, transport, say });
-    if (values.json) out(jsonText({ ...(report ?? { local: true }), notes: lines }));
+    const report = await app.syncHere({ cwd, transport, say, dryRun });
+    if (values.json)
+      out(
+        jsonText({ ...(report ?? { local: true }), ...(dryRun ? { dryRun } : {}), notes: lines }),
+      );
     return 0;
   }
 
@@ -1087,7 +1121,12 @@ export async function run(argv, io = {}) {
     }
     case "whoami": {
       none(parse(spec()).positionals);
-      return call("list_harbors", {}, (r) => whoami(r, creds));
+      return call(
+        "list_harbors",
+        {},
+        (r) => whoami(r, creds),
+        (r) => whoamiData(r, creds),
+      );
     }
     case "use": {
       const { positionals } = parse({ flags: ["json"], options: [] });
@@ -1251,6 +1290,7 @@ export async function run(argv, io = {}) {
               .split(",")
               .map((x) => x.trim())
               .filter(Boolean)
+              .map(statusWord)
           : undefined,
         overdue: values.late || undefined,
       };
@@ -1463,7 +1503,7 @@ export async function run(argv, io = {}) {
           assignee: values.assignee ?? "me",
           due: dueDate(values.due),
           priority: values.priority,
-          status: values.status,
+          status: values.status === undefined ? undefined : statusWord(values.status),
           overLimit: values["over-limit"] || undefined,
         },
         (r) => `Added: ${taskLine(r.created, opts)}`,
@@ -1512,7 +1552,7 @@ export async function run(argv, io = {}) {
           assignee: values.assignee,
           due: values.due === undefined ? undefined : nullable(dueDate(values.due)),
           priority: values.priority,
-          status: values.status,
+          status: values.status === undefined ? undefined : statusWord(values.status),
           description: values.notes,
           repeat: values.repeat,
           waitsOn:
@@ -1630,6 +1670,8 @@ export async function run(argv, io = {}) {
         "export_csv",
         { harbor, what, project: project || undefined, all: Boolean(values.all) },
         (r) => r.csv.replace(/\r\n/g, "\n"),
+        // --json: the rows, each keyed by its column, not one CSV string.
+        (r) => (asJson ? exportData(r) : r),
       );
     }
     case "import": {
@@ -1709,7 +1751,7 @@ export async function run(argv, io = {}) {
       if (limit !== null && !(Number.isInteger(limit) && limit >= 1 && limit <= 20)) {
         throw new HarborError("A limit is a whole number from 1 to 20, or none.");
       }
-      return call("set_column_limit", { harbor, project, column, limit }, (r) =>
+      return call("set_column_limit", { harbor, project, column: statusWord(column), limit }, (r) =>
         limitsText(r.set.project, r.limits, r.tasks, r.hiddenColumns),
       );
     }
@@ -1724,7 +1766,13 @@ export async function run(argv, io = {}) {
       if (!note) {
         if (values.opens || values.milestone || values["off-track"])
           throw new HarborError("Write the note too, in quotes after the project.");
-        return call("get_project", { harbor, project }, (r) => notesText(r.name, r.notesForLater));
+        // --json: the project and its notes, an empty list when there are none.
+        return call(
+          "get_project",
+          { harbor, project },
+          (r) => notesText(r.project, r.notes),
+          (r) => ({ id: r.id, project: r.name, notes: r.notesForLater ?? [] }),
+        );
       }
       return call(
         "leave_note",
@@ -1805,7 +1853,7 @@ export async function run(argv, io = {}) {
         "agent_update",
         { harbor, task, note, status: values.start ? "doing" : "review", agent: values.agent },
         (r) =>
-          `${r.updated.key ?? r.updated.title} is ${r.updated.status === "review" ? "in review for a person to check" : "in progress"}, with ${r.commentedAs}'s note.`,
+          `${r.updated.key ?? r.updated.title} is ${r.updated.status === "review" ? "in review for a person to check" : "in play"}, with ${r.commentedAs}'s note.`,
       );
     }
     case "handback": {

package/lib/format.mjs

@@ -1,13 +1,30 @@
 /** Plain text for a terminal: one task per line, its key (or id) first so it can be copied. */
 
+/** Statuses in the board's words, as the website, the app and an export say them. */
 export const STATUS = {
   backlog: "backlog",
   todo: "to do",
-  doing: "doing",
+  doing: "in play",
   review: "review",
   done: "done",
 };
 
+/**
+ * A status as someone typed it: Harbor's own (doing) or the board's (In play,
+ * To do), any case, with a space, a hyphen or neither. Anything else comes
+ * back as typed, for Harbor to refuse with the list.
+ */
+export function statusWord(typed) {
+  const v = String(typed)
+    .trim()
+    .toLowerCase()
+    .replace(/[\s_-]+/g, "");
+  return (
+    { inplay: "doing", inprogress: "doing", todo: "todo", inreview: "review" }[v] ??
+    (["backlog", "doing", "review", "done"].includes(v) ? v : String(typed).trim())
+  );
+}
+
 /**
  * `mine` leaves out whose each task is: every one is yours. `width` (the
  * terminal's, when printing to one) shortens a long title so the line fits;
@@ -191,6 +208,25 @@ export function whoami(r, creds) {
   return lines.join("\n");
 }
 
+/** whoami --json: the account and its harbors, with where it signed in and the harbor commands use. */
+export function whoamiData(r, creds) {
+  const list = r.harbors ?? [];
+  const set = creds.harbor ? list.find((h) => h.id === creds.harbor) : null;
+  const using = set
+    ? { id: set.id, name: set.name, from: "harbor use" }
+    : creds.harbor
+      ? { id: creds.harbor, name: creds.harborName ?? null, from: "harbor use", left: true }
+      : list.length === 1
+        ? { id: list[0].id, name: list[0].name, from: "your only harbor" }
+        : null;
+  return {
+    ...r,
+    server: creds.server,
+    readOnly: !creds.scope?.split(" ").includes("harbor:write"),
+    harbor: using,
+  };
+}
+
 export function harbors(r) {
   const list = r.harbors ?? [];
   if (!list.length) return "You aren't in any harbor yet. Run harbor to make one.";
@@ -310,7 +346,7 @@ export function forecastOne(p) {
   if (f.lastDue) {
     const which = f.lastDue.key ? `${f.lastDue.key} “${f.lastDue.title}”` : `“${f.lastDue.title}”`;
     lines.push(
-      `${which} is due ${f.lastDue.due}, after the likely finish, so the plan runs longer than the pace says.`,
+      `${which} is due ${f.lastDue.due}, later than the crew's pace alone would finish, so the dates wait for it.`,
     );
   }
   return lines.join("\n");
@@ -318,13 +354,17 @@ export function forecastOne(p) {
 
 /** forecast --json: the finish forecast itself, with only what names the project around it. */
 export function forecastData(r) {
+  // The same fields every time, so a script needn't test for them; notes are
+  // what the pace can't see, as the list shows them.
   const one = (p) => ({
     id: p.id,
     name: p.name,
     ...(p.key ? { key: p.key } : {}),
     ...(p.program !== undefined ? { program: p.program } : {}),
     ends: p.ends ?? null,
+    ...(p.finish?.none ? {} : { rough: false, shortHistory: false, lastDue: null }),
     ...p.finish,
+    notes: p.finish?.none ? [] : finishNotes(p.finish ?? {}),
   });
   if (!r.projects) return one(r);
   return { projects: r.projects.filter((p) => p.health !== "done").map(one) };
@@ -533,7 +573,7 @@ export function agentWorkText(r) {
   const lines = [`Work for ${r.agent}${r.addedBy ? ` (added by ${r.addedBy})` : ""}`];
   if (!r.tasks?.length) lines.push("", "Nothing to do: no open tasks are assigned to it.");
   for (const t of r.tasks ?? []) {
-    const bits = [t.status === "doing" ? "in progress" : t.status, t.priority];
+    const bits = [STATUS[t.status] ?? t.status, t.priority];
     if (t.due) bits.push(`due ${t.due}`);
     lines.push(
       "",
@@ -555,3 +595,43 @@ export function agentWorkText(r) {
   );
   return lines.join("\n");
 }
+
+/** CSV text as rows of cells: quoted cells may hold commas, quotes ("") and line breaks. */
+export function csvRows(text) {
+  const rows = [];
+  let row = [];
+  let cell = "";
+  let quoted = false;
+  for (let i = 0; i < text.length; i++) {
+    const c = text[i];
+    if (quoted) {
+      if (c === '"' && text[i + 1] === '"') {
+        cell += '"';
+        i++;
+      } else if (c === '"') quoted = false;
+      else cell += c;
+    } else if (c === '"') quoted = true;
+    else if (c === ",") {
+      row.push(cell);
+      cell = "";
+    } else if (c === "\n" || c === "\r") {
+      if (c === "\r" && text[i + 1] === "\n") i++;
+      row.push(cell);
+      rows.push(row);
+      row = [];
+      cell = "";
+    } else cell += c;
+  }
+  if (cell || row.length) rows.push([...row, cell]);
+  return rows;
+}
+
+/** export --json: each row as an object keyed by the file's headers, not one CSV string. */
+export function exportData(r) {
+  const [columns = [], ...body] = csvRows(r.csv ?? "");
+  return {
+    filename: r.filename,
+    columns,
+    rows: body.map((cells) => Object.fromEntries(columns.map((c, i) => [c, cells[i] ?? ""]))),
+  };
+}

package/package.json

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