@harborppm/cli 0.36.0 → 0.37.0

package/lib/cli.mjs

@@ -86,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]
@@ -389,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",
@@ -642,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(
@@ -840,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));

package/package.json

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