@harborppm/cli 0.36.0 → 0.38.0

package/lib/cli.mjs

@@ -17,6 +17,8 @@ import {
   writeSettings,
 } from "./config.mjs";
 import {
+  forecastData,
+  importText,
   forecastList,
   forecastOne,
   STATUS,
@@ -86,6 +88,14 @@ export const HELP = `harbor: Harbor from the terminal
   harbor roadmap PROJECT [--dates|--no-dates] [--off]
                                               publish a project's public roadmap
 
+  harbor init [PROJECT] [--hook]              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
+                                              and bring its changes back
+
   harbor program "NAME" [--portfolio P] [--lead me|NAME] [--starts DATE]
                        [--ends DATE]
   harbor project "NAME" --program P [--lead me|NAME] [--starts DATE]
@@ -114,6 +124,10 @@ export const HELP = `harbor: Harbor from the terminal
                                               --say reads it aloud as a
                                               shipping forecast
   harbor report PROGRAM                       a program's status report
+  harbor export tasks PROJECT|risks|review [--all]
+                                              a spreadsheet (CSV) to stdout
+  harbor import FILE [--project P] [--portfolio P] [--no-people]
+                                              add tasks from a CSV file
   harbor premortem PROJECT ["WHAT WENT WRONG"] [--start]
                                               a project's pre-mortem: start,
                                               answer or read it
@@ -389,6 +403,30 @@ export function voyageForTerminal(r, project = r.project) {
 
 /** Commands whose forms do different things: one line each, saying which read and which write. */
 const DETAIL = {
+  init: [
+    "  harbor init [PROJECT] [--hook]         writes: .harbor/ at the top of this",
+    "                                         repository, one file per task in",
+    "                                         PROJECT (a key like RR or a name;",
+    "                                         the folder's name when left out)",
+    "  harbor init --local [NAME]             writes: a plan that lives only in",
+    "                                         this folder, with no account;",
+    "                                         harbor here opens it full screen",
+    "",
+    "  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",
+    "  a git post-commit hook that runs harbor sync after each commit. Run init on",
+    "  a local plan to move its tasks into PROJECT.",
+  ],
+  sync: [
+    "  harbor sync [--quiet]                  writes: sends what the files changed to",
+    "                                         Harbor and rewrites the files from it",
+    "",
+    "  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.",
+  ],
   limit: [
     "  harbor limit PROJECT                   reads its board's column limits",
     "  harbor limit PROJECT COLUMN N          writes: COLUMN takes at most N tasks",
@@ -412,6 +450,45 @@ const DETAIL = {
     "  PROJECT is a name, a key like RR, or an id. When two projects share a",
     "  name, give the key.",
   ],
+  forecast: [
+    "  harbor forecast [--program P]          reads when each open project will",
+    "                                         likely finish",
+    "  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",
+    "  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.",
+  ],
+  report: [
+    "  harbor report PROGRAM                  reads the program's status report",
+    "",
+    "  Prints Markdown, as the website's Status report button writes it:",
+    "  health, progress, late work, milestones, risks and the next move.",
+    "  Ready to paste; harbor report PROGRAM > report.md saves it.",
+  ],
+  export: [
+    "  harbor export tasks PROJECT            reads a project's tasks as CSV",
+    "  harbor export risks [--all]            reads the risk register as CSV",
+    "                                         (--all adds closed ones)",
+    "  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.",
+  ],
+  import: [
+    "  harbor import FILE --project P         writes: adds the file's tasks",
+    "  harbor import FILE --portfolio P       writes: makes projects as the file",
+    "                                         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",
+    "  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.",
+  ],
   note: [
     "  harbor note PROJECT                    reads its notes for later: who left",
     "                                         each, what opens it, and the opened ones",
@@ -475,6 +552,21 @@ const DETAIL = {
     "  PROJECT is a name, a key like RR, or an id. When two projects share a",
     "  name, give the key.",
   ],
+  risk: [
+    '  harbor risk "TITLE" --project P        writes: logs a risk on the project',
+    '  harbor risk "TITLE" --program P        writes: logs one on the program',
+    "      [--impact 1-5] [--probability 1-5] [--owner NAME] [--due DATE]",
+  ],
+  issue: [
+    '  harbor issue "TITLE" --project P       writes: logs an issue on the project',
+    '  harbor issue "TITLE" --program P       writes: logs one on the program',
+    "      [--impact 1-5] [--owner NAME] [--due DATE]",
+  ],
+  decision: [
+    '  harbor decision "TITLE" --project P    writes: logs a decision to make',
+    '  harbor decision "TITLE" --program P    writes: logs one on the program',
+    "      [--owner NAME] [--due DATE] (the date to decide by)",
+  ],
 };
 
 /** The lines of the help about one command, or null when it has none. */
@@ -642,6 +734,15 @@ export async function run(argv, io = {}) {
     }
     if (!terminal) throw new HarborError("The full-screen app needs a terminal.");
     const { values } = parseArgs(rest, { flags: [], options: ["harbor", "server"] });
+    // In a folder with a local plan (harbor init --local), the app opens on it.
+    if (!values.harbor && !values.server) {
+      const bundled = await loadApp();
+      const dir = await bundled.localPlanAt(io.cwd ?? process.cwd());
+      if (dir) {
+        await bundled.runLocalApp({ dir, theme: (await readSettings(env)).theme });
+        return 0;
+      }
+    }
     let creds = await readCredentials(env);
     if (!hasFullAccess(creds)) {
       out(
@@ -840,6 +941,75 @@ export async function run(argv, io = {}) {
     return 0;
   }
 
+  if (command === "init" || command === "sync") {
+    const init = command === "init";
+    const { values, positionals } = parseArgs(rest, {
+      flags: init ? ["local", "hook", "json"] : ["quiet", "json"],
+      options: init ? ["harbor"] : [],
+    });
+    const cwd = io.cwd ?? process.cwd();
+    const lines = [];
+    const say = values.json
+      ? (line) => lines.push(line)
+      : values.quiet
+        ? (line) => {
+            if (!line.startsWith("⚓")) out(plain(line));
+          }
+        : (line) => out(plain(line));
+    const app = await loadApp();
+    if (init && values.local) {
+      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 });
+      if (values.json) out(jsonText({ plan: config, notes: lines }));
+      return 0;
+    }
+    if (positionals.length > (init ? 1 : 0))
+      throw new HarborError(
+        init
+          ? "harbor init takes one project; put a name with spaces in quotes."
+          : "harbor sync takes no words; it syncs the plan of the folder you're in.",
+      );
+    // Plans move through /api/app, as the full-screen app does: full access.
+    const transport = async () => {
+      const creds = await readCredentials(env);
+      if (!hasFullAccess(creds))
+        throw new HarborError(
+          creds
+            ? "This sign-in can only read. Run harbor login (without --read-only) to keep plans in step."
+            : "Not signed in. Run harbor login, or harbor signup if you're new; harbor init --local needs no account.",
+        );
+      return app.planTransport(
+        tokenSource({ creds, save: (c) => writeCredentials(c, env), fetcher }),
+        fetcher,
+      );
+    };
+    if (init) {
+      const creds = await readCredentials(env);
+      const config = await app.initHere({
+        cwd,
+        transport: await transport(),
+        project: positionals[0],
+        hook: Boolean(values.hook),
+        say,
+        pickHarbor: (list) => {
+          if (values.harbor) return app.harborNamed(list, values.harbor);
+          const saved = list.find((h) => h.id === creds?.harbor);
+          if (saved) return saved;
+          if (list.length === 1) return list[0];
+          throw new HarborError(
+            `You're in ${list.length} harbors (${list.map((h) => h.name).join(", ")}). Add --harbor NAME, or run harbor use NAME first.`,
+          );
+        },
+      });
+      if (values.json) out(jsonText({ plan: config, notes: lines }));
+      return 0;
+    }
+    const report = await app.syncHere({ cwd, transport, say });
+    if (values.json) out(jsonText({ ...(report ?? { local: true }), notes: lines }));
+    return 0;
+  }
+
   // A mistyped command says so, signed in or not.
   if (commandHelp(command) === null) {
     throw new HarborError(noCommand(command));
@@ -984,8 +1154,21 @@ export async function run(argv, io = {}) {
     case "forecast": {
       const { positionals, values, harbor } = parse(spec([], ["program"]));
       const project = positionals.join(" ").trim();
-      if (project) return call("get_project", { harbor, project }, forecastOne);
-      return call("list_projects", { harbor, program: values.program, limit: 100 }, forecastList);
+      // --json gets each forecast flat beside the project's name (forecastData).
+      const withFinish = (p) => ({ ...p, finish: p });
+      if (project)
+        return call(
+          "get_project",
+          { harbor, project },
+          (d) => forecastOne(withFinish(d)),
+          forecastData,
+        );
+      return call(
+        "list_projects",
+        { harbor, program: values.program, limit: 100 },
+        (d) => forecastList({ projects: d.projects.map(withFinish) }),
+        forecastData,
+      );
     }
     case "hill": {
       const { positionals, values, harbor } = parse(spec([], ["program", "at"]));
@@ -1365,6 +1548,44 @@ export async function run(argv, io = {}) {
       if (!program) throw new HarborError('Give a program: harbor report "NAME".');
       return call("status_report", { harbor, program }, (r) => r.markdown);
     }
+    case "export": {
+      const { positionals, values, harbor } = parse(spec(["all"]));
+      const [what, ...name] = positionals;
+      if (!["tasks", "risks", "review"].includes(what))
+        throw new HarborError("Say what to export: harbor export tasks PROJECT, risks or review.");
+      const project = name.join(" ").trim();
+      if (what === "tasks" && !project)
+        throw new HarborError('Give the project: harbor export tasks "NAME".');
+      if (what !== "tasks") none(name);
+      return call(
+        "export_csv",
+        { harbor, what, project: project || undefined, all: Boolean(values.all) },
+        (r) => r.csv.replace(/\r\n/g, "\n"),
+      );
+    }
+    case "import": {
+      const { positionals, values, harbor } = parse(spec(["no-people"], ["project", "portfolio"]));
+      const [file, ...extra] = positionals;
+      if (!file) throw new HarborError("Give the file: harbor import tasks.csv --project NAME.");
+      none(extra);
+      let csv;
+      try {
+        csv = readFileSync(file, "utf8");
+      } catch {
+        throw new HarborError(`Can't read ${file}.`);
+      }
+      return call(
+        "import_tasks",
+        {
+          harbor,
+          csv,
+          project: values.project,
+          portfolio: values.portfolio,
+          addPeople: !values["no-people"],
+        },
+        importText,
+      );
+    }
     case "premortem": {
       const { positionals, values, harbor } = parse(spec(["start"]));
       const [project, ...words] = positionals;

package/lib/format.mjs

@@ -216,9 +216,32 @@ function chance(c) {
   return `${Math.round(c * 20) * 5}%`;
 }
 
+/**
+ * The forecast's dates as phrases, a date said once: when half and 85% of
+ * runs finish the same day, "very likely by" it is. At most `most` of them.
+ */
+function finishPhrases(f, most = 3) {
+  const steps = [
+    [f.likely, "probably"],
+    [f.veryLikely, "very likely by"],
+    [f.almostCertain, "almost certainly by"],
+  ].filter(([date]) => date);
+  const kept = steps.filter(([date], i) => date !== steps[i + 1]?.[0]);
+  return kept.slice(0, most).map(([date, words]) => `${words} ${date}`);
+}
+
 function finishRange(f) {
   if (!f.likely) return "not in the next two years at this pace";
-  return `probably ${f.likely}${f.veryLikely ? `, very likely by ${f.veryLikely}` : ""}`;
+  return finishPhrases(f, 2).join(", ");
+}
+
+/** What the pace can't see, as short notes for the list. */
+function finishNotes(f) {
+  return [
+    f.rough ? "rough" : null,
+    f.shortHistory ? "under 2 weeks of pace" : null,
+    f.lastDue ? `${f.lastDue.key ?? `“${f.lastDue.title}”`} due ${f.lastDue.due}` : null,
+  ].filter(Boolean);
 }
 
 /** When each open project will likely finish at its crew's recent pace. */
@@ -232,7 +255,7 @@ export function forecastList(r) {
       const name = p.name.length > width ? `${p.name.slice(0, width - 1)}…` : p.name.padEnd(width);
       if (f.none) return `${name}  no forecast: ${f.none.replace(/^\w/, (c) => c.toLowerCase())}`;
       const end = p.ends ? ` · ${chance(f.chanceByEnd)} by its end, ${p.ends}` : "";
-      return `${name}  ${finishRange(f)}${end}${f.rough ? " · rough" : ""}`;
+      return [`${name}  ${finishRange(f)}${end}`, ...finishNotes(f)].join(" · ");
     })
     .join("\n");
 }
@@ -241,10 +264,10 @@ export function forecastList(r) {
 export function forecastOne(p) {
   const f = p.finish ?? {};
   if (f.none) return `${p.name}: ${f.none}`;
-  const range = finishRange(f);
+  const [first, ...more] = finishPhrases(f);
   const lines = [
     f.likely
-      ? `${p.name} will ${range.replace(/^probably/, "probably finish")}${f.almostCertain ? `, almost certainly by ${f.almostCertain}` : ""}.`
+      ? `${p.name} will ${first.replace(/^(probably|very likely|almost certainly)/, "$1 finish")}${more.map((x) => `, ${x}`).join("")}.`
       : `${p.name} won't finish in the next two years at this pace.`,
   ];
   if (p.ends) {
@@ -255,9 +278,33 @@ export function forecastOne(p) {
     `${f.openTasks} task${f.openTasks === 1 ? "" : "s"} open; the crew finishes about ${f.finishedPerWeek} a week (${f.basedOn}).`,
   );
   if (f.rough) lines.push("Only a few tasks have finished, so treat this as rough.");
+  if (f.shortHistory)
+    lines.push(
+      "That pace comes from under two weeks of work; tasks logged as done in a batch make it look faster than it is.",
+    );
+  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.`,
+    );
+  }
   return lines.join("\n");
 }
 
+/** forecast --json: the finish forecast itself, with only what names the project around it. */
+export function forecastData(r) {
+  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,
+  });
+  if (!r.projects) return one(r);
+  return { projects: r.projects.filter((p) => p.health !== "done").map(one) };
+}
+
 /** A project's pre-mortem, as get_premortem answers it. */
 export function premortemText(r) {
   if (!r.running) {
@@ -370,6 +417,25 @@ export function hillList(r) {
   return blocks.join("\n\n");
 }
 
+/** What harbor import did, as import_tasks answers it. */
+export function importText(r) {
+  const n = (count, word) => `${count} ${word}${count === 1 ? "" : "s"}`;
+  const from = r.from ? ` from ${r.from}` : "";
+  const lines = [
+    r.imported
+      ? `Imported ${n(r.imported, "task")}${from} into ${r.portfolio}.`
+      : `Nothing imported${from}.`,
+  ];
+  if (r.newPrograms?.length) lines.push(`New programs: ${r.newPrograms.join(", ")}.`);
+  if (r.newProjects?.length) lines.push(`New projects: ${r.newProjects.join(", ")}.`);
+  if (r.newPeople?.length) lines.push(`New people: ${r.newPeople.join(", ")}.`);
+  if (r.alreadyThere) lines.push(`${n(r.alreadyThere, "task")} already there, left alone.`);
+  if (r.leftOut) lines.push(`${n(r.leftOut, "row")} left out (canceled, won't do or duplicate).`);
+  if (r.waitsOnLinks) lines.push(`${n(r.waitsOnLinks, "link")} between tasks became "waits on".`);
+  for (const p of r.problems ?? []) lines.push(`Row ${p.row}: ${p.message}`);
+  return lines.join("\n");
+}
+
 /** A project's notes for later, as get_project lists them. */
 export function notesText(project, notes) {
   if (!notes?.length)

package/package.json

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