@harborppm/cli 0.10.1 → 0.11.0

package/README.md

@@ -55,6 +55,8 @@ Your harbor is the same one at [harborppm.com](https://harborppm.com/today?utm_s
 - **GitHub**: a pull request that names a task's key (RR-42) shows on the task and moves it along.
 - **Claude and other AI apps**, connected over MCP from [harborppm.com/ai](https://harborppm.com/ai?utm_source=npm&utm_medium=readme&utm_campaign=cli).
 
+`harbor open RR-42` opens a task on the website (in the right harbor, even when the browser had another one open), `harbor open Ridge` a project, and `harbor open` on its own opens Today. `harbor invite sam@example.com` sends Sam the same invite letter the People page does (`--viewer` to let them look but not change anything); only a harbor's owner can invite.
+
 The website has the commands too: turn on **Command line at the bottom** in your menu, press `/`, and type `mine`, `add "Call the mill" #ridge @sam --due fri` or `done RR-12`.
 
 ## Staying up to date
@@ -80,7 +82,9 @@ harbor programs                             programs and their projects
 harbor projects [words] [--program P]       projects with health and open work
 harbor mine                                 what's on you, late first
 harbor tasks [words] [--project P] [--assignee me|none|NAME] [--late] [--status S,S]
-harbor show TASK                            one task in full
+harbor show TASK                            one task in full, with its web link
+harbor open [TASK|PROJECT]                  open it on the website (or Today)
+harbor invite EMAIL [--viewer]              invite someone to your harbor by email
 
 harbor program "NAME" [--portfolio P] [--lead me|NAME] [--starts DATE]
                      [--ends DATE]

package/lib/cli.mjs

@@ -46,6 +46,8 @@ export const HELP = `harbor: Harbor from the terminal
   harbor tasks [words] [--project P] [--assignee me|none|NAME]
                      [--late] [--status S,S]
   harbor show TASK                            one task (TASK: a key like RR-42)
+  harbor open [TASK|PROJECT]                  open it on the website (or Today)
+  harbor invite EMAIL [--viewer]              invite someone to your harbor
 
   harbor program "NAME" [--portfolio P] [--lead me|NAME] [--starts DATE]
                        [--ends DATE]
@@ -270,6 +272,41 @@ const none = (positionals) => {
   if (positionals.length) throw new HarborError(`Unexpected "${positionals.join(" ")}".`);
 };
 
+/** The harbor a --harbor key (or `harbor use`) names, the only one, or null when there are several. */
+async function harborNamed(client, key) {
+  const { harbors } = await client.call("list_harbors", {});
+  if (!key) return harbors.length === 1 ? harbors[0] : null;
+  const k = key.toLowerCase();
+  const hits = harbors.filter((h) => h.id === key || h.name.trim().toLowerCase() === k);
+  if (hits.length === 1) return hits[0];
+  throw new HarborError(`No harbor matches "${key}". Run harbor harbors.`);
+}
+
+const TASK_KEY = /^[A-Za-z][A-Za-z0-9]{0,9}-\d+$/;
+
+/**
+ * A task by its key, else a project by name, else a task by id: its web
+ * link and what to call it. Harbor's own refusal when nothing matches.
+ */
+async function findOpenable(client, harbor, wanted) {
+  const task = async () => {
+    const t = await client.call("get_task", { harbor, task: wanted });
+    return { url: t.url, what: t.key ? `${t.key} ${t.title}` : t.title };
+  };
+  const wrap = (err) => {
+    if (err instanceof HarborError) throw new HarborError(hint(err.message));
+    throw err;
+  };
+  if (TASK_KEY.test(wanted)) return task().catch(wrap);
+  try {
+    const p = await client.call("get_project", { harbor, project: wanted });
+    return { url: p.url, what: p.name };
+  } catch (err) {
+    if (!(err instanceof HarborError) || !/^No project matches/.test(err.message)) wrap(err);
+    return task().catch(() => wrap(err));
+  }
+}
+
 export async function run(argv, io = {}) {
   const out = io.out ?? ((s) => process.stdout.write(`${s}\n`));
   const env = io.env ?? process.env;
@@ -641,9 +678,64 @@ export async function run(argv, io = {}) {
             "",
             ...t.comments.map((c) => `${c.author ?? "Someone"}, ${c.at.slice(0, 10)}: ${c.body}`),
           );
+        if (t.url) lines.push("", `On the web: ${t.url}`);
         return lines.join("\n");
       });
     }
+    case "open": {
+      const { positionals, harbor } = parse(spec());
+      const wanted = positionals.join(" ").trim();
+      let url;
+      let what = "Today";
+      if (!wanted) {
+        const ref = await harborNamed(client, harbor);
+        url = new URL("/open", creds.server);
+        if (ref) url.searchParams.set("harbor", ref.id);
+        url = url.toString();
+        if (ref) what = `Today in ${ref.name}`;
+      } else {
+        const found = await findOpenable(client, harbor, wanted);
+        url = found.url;
+        what = found.what;
+      }
+      if (!url) throw new HarborError("This Harbor doesn't give web links yet.");
+      if (asJson) {
+        out(jsonText({ url }));
+        return 0;
+      }
+      out(plain(`Opening ${what} in your browser. If it doesn't open, go to:\n\n  ${url}`));
+      (io.browse ?? openBrowser)(url);
+      return 0;
+    }
+    case "invite": {
+      const { positionals, values, harbor } = parse(spec(["viewer"]));
+      const email = one(positionals, "email address");
+      if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) {
+        throw new HarborError(`"${email}" isn't an email address.`);
+      }
+      if (!hasFullAccess(creds)) {
+        throw new HarborError("Inviting needs full access. Run harbor login, then try again.");
+      }
+      const r = await client.app({
+        op: "invite",
+        ...(harbor ? { harbor } : {}),
+        email,
+        role: values.viewer ? "viewer" : "member",
+      });
+      if (asJson) {
+        out(jsonText(r));
+        return 0;
+      }
+      const as = r.role === "viewer" ? "a viewer (they can look, not change)" : "a member";
+      out(
+        plain(
+          r.sent
+            ? `Invited ${r.email} to ${r.harbor} as ${as}. Harbor emailed them the invite; they join on the website or with harbor login.`
+            : `Made an invite for ${r.email} to ${r.harbor} as ${as}, but Harbor didn't email it (it sends invites once your own email address is confirmed). Send them this link yourself:\n\n  ${r.link}`,
+        ),
+      );
+      return 0;
+    }
     case "add": {
       const { positionals, values, harbor } = parse(
         spec(["over-limit"], ["project", "assignee", "due", "priority", "status"]),

package/lib/mcp.mjs

@@ -19,8 +19,8 @@ export function createClient({ creds, save, fetcher = fetch, now = Date.now }) {
     await save(current);
   }
 
-  async function post(body) {
-    return reach(fetcher, new URL("/api/mcp", current.server), {
+  async function post(body, path = "/api/mcp") {
+    return reach(fetcher, new URL(path, current.server), {
       method: "POST",
       headers: {
         "content-type": "application/json",
@@ -57,5 +57,23 @@ export function createClient({ creds, save, fetcher = fetch, now = Date.now }) {
         throw new HarborError(result.content?.map((c) => c.text).join("\n") || "Harbor said no.");
       return result.structuredContent ?? JSON.parse(result.content?.[0]?.text ?? "{}");
     },
+
+    /**
+     * One request to the full-access door the terminal app uses (/api/app):
+     * what the MCP tools don't do, like `harbor invite`. Harbor's refusal
+     * comes back as a HarborError in its own words.
+     */
+    async app(body) {
+      if (current.expiresAt - SKEW_MS < now()) await renew();
+      let res = await post(body, "/api/app");
+      if (res.status === 401) {
+        await renew();
+        res = await post(body, "/api/app");
+      }
+      if (res.status === 401) throw new HarborError("Signed out. Run harbor login.");
+      const answer = await res.json().catch(() => ({}));
+      if (!res.ok) throw new HarborError(answer.error ?? `Harbor answered ${res.status}.`);
+      return answer;
+    },
   };
 }

package/package.json

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