@harborppm/cli 0.35.0 → 0.37.0

package/lib/cli.mjs

@@ -29,6 +29,7 @@ import {
   notesText,
   voyageText,
   handoverText,
+  agentWorkText,
   raidList,
   programTree,
   projectList,
@@ -85,6 +86,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]
@@ -125,6 +134,11 @@ export const HELP = `harbor: Harbor from the terminal
                          [--keep ID,ID] [--confirm]
                                               hand someone's work to the crew
   harbor handback PERSON                      give it back after time away
+  harbor agent [--agent NAME]                 the tasks given to an AI agent on
+                                              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)
 
   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.
@@ -383,6 +397,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",
@@ -434,6 +472,33 @@ const DETAIL = {
     "",
     '  PERSON is a name, an id, or "me".',
   ],
+  handback: [
+    "  harbor handback PERSON                 writes, straight away: gives back",
+    "                                         what was handed over for their time",
+    "                                         away and is still with whoever took",
+    "                                         it, and stops showing them as away",
+    "",
+    "  Anything someone else has since taken, finished or closed stays where it",
+    "  is. If PERSON isn't marked away, it says so and changes nothing.",
+    "  harbor handover PERSON --until DATE is what marks someone away.",
+    "",
+    '  PERSON is a name, an id, or "me".',
+  ],
+  agent: [
+    "  harbor agent                           reads the tasks people gave the crew's",
+    "                                         agent (an AI crew member on People),",
+    "                                         in progress 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",
+    "",
+    "  --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.",
+  ],
   voyage: [
     "  harbor voyage PROJECT                  reads a Done project's voyage log",
     '  harbor voyage PROJECT "YOUR LINE"      writes: adds or changes your line in it',
@@ -609,6 +674,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(
@@ -807,6 +881,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));
@@ -1461,6 +1604,25 @@ export async function run(argv, io = {}) {
         },
       );
     }
+    case "agent": {
+      const { positionals, values, harbor } = parse(spec(["start"], ["agent"]));
+      if (positionals[0] !== "report") {
+        none(positionals);
+        return call("agent_work", { harbor, agent: values.agent }, agentWorkText);
+      }
+      const [, task, ...words] = positionals;
+      const note = words.join(" ").trim();
+      if (!task || !note)
+        throw new HarborError(
+          'Give the task and what the agent did: harbor agent report RR-4 "Drafted it".',
+        );
+      return call(
+        "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.`,
+      );
+    }
     case "handback": {
       const { positionals, harbor } = parse(spec());
       const person = positionals.join(" ").trim();

package/lib/format.mjs

@@ -412,9 +412,19 @@ export function handoverText(r, { confirmHint = true } = {}) {
       group = i.group;
       lines.push("", `${group}:`);
     }
+    const due = i.due && i.kind !== "project" && i.kind !== "program" ? ` (${i.due})` : "";
+    lines.push(`  ${i.what}${due}${i.to ? `  → ${i.to}` : ""}`);
+  }
+  if (r.nobodyToTake) {
     lines.push(
-      `  ${i.what}${i.due && i.kind !== "project" && i.kind !== "program" ? ` (${i.due})` : ""}  → ${i.to ?? "nobody yet"}`,
+      "",
+      `${r.nobodyToTake} Invite someone with harbor invite EMAIL, then run this again.`,
     );
+    if (confirmHint)
+      lines.push(
+        `Until then, --confirm moves nothing; with --until DATE it only marks ${r.person} as away.`,
+      );
+    return lines.join("\n");
   }
   const room = (r.takers ?? []).filter((t) => t.note).map((t) => `${t.who} ${t.note}`);
   if (room.length) lines.push("", `This week: ${room.join(", ")}.`);
@@ -425,3 +435,32 @@ export function handoverText(r, { confirmHint = true } = {}) {
     );
   return lines.join("\n");
 }
+
+/** agent_work: the agent's tasks in the order to do them, then what waits on a person. */
+export function agentWorkText(r) {
+  if (!r.agent) return r.note;
+  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];
+    if (t.due) bits.push(`due ${t.due}`);
+    lines.push(
+      "",
+      `${t.key ?? t.id}  ${t.title}  (${bits.join(", ")}${t.project ? `, ${t.project}` : ""})`,
+    );
+    if (t.notes) lines.push(...t.notes.split("\n").map((l) => `    ${l}`));
+    for (const c of t.checklist ?? []) lines.push(`    [${c.done ? "x" : " "}] ${c.step}`);
+    for (const c of t.comments ?? []) lines.push(`    ${c.author ?? "Someone"}: ${c.body}`);
+  }
+  if (r.total > (r.tasks ?? []).length) lines.push("", `…and ${r.total - r.tasks.length} more.`);
+  if (r.forReview?.length)
+    lines.push(
+      "",
+      `Waiting for a person to check: ${r.forReview.map((t) => t.key ?? t.title).join(", ")}.`,
+    );
+  lines.push(
+    "",
+    'When a task is done, harbor agent report TASK "WHAT YOU DID" moves it to In review for a person to check.',
+  );
+  return lines.join("\n");
+}

package/package.json

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