@harborppm/cli 0.10.0 → 0.11.0

package/README.md

@@ -12,7 +12,7 @@ Needs Node 22 or later.
 
 ## New to Harbor?
 
-You can start from the terminal. Harbor is free to start.
+You can start from the terminal. A harbor of your own is free for 30 days, no card; after that it's $49 a month for the whole crew, not per seat.
 
 ```sh
 npm install -g @harborppm/cli
@@ -39,10 +39,26 @@ A task changes in place too: title, status, owner, due date (`2026-10-14`, `toda
 
 Keys: `↑↓` (or `j k`) and `←→` (or `h l`) move, Enter opens, Esc goes back, `:` finds anything (a screen, "new project", a project or program by name), `/` finds a task by its key or words, `n` makes something new, `e` changes what's open, `[` `]` move a card a column, `x` marks it done, `d` deletes (it asks first), `u` undoes your last change, `H` switches harbor, `?` lists them all.
 
+It runs on the same engine as the website: health, task keys, limits and undo work the same way, changes save as you go (the header says when, and holds them while you're offline), and changes anyone makes on the website or elsewhere show up within a couple of seconds. It needs full access, which `harbor login` asks for by name; an older sign-in is asked again the first time.
+
 It has colours for dark terminals and for light ones, and picks by asking the terminal for its background (or reading `COLORFGBG`); a terminal that doesn't say gets the dark ones. `harbor theme light` or `harbor theme dark` settles it, `harbor theme auto` goes back to asking, and `HARBOR_THEME` overrides it for one run.
 
 `harbor help` shows the mark too, in a terminal with colour; piped, or with `NO_COLOR` set, it's plain text. `harbor --version` says which version you have.
 
+## On the website
+
+Your harbor is the same one at [harborppm.com](https://harborppm.com/today?utm_source=npm&utm_medium=readme&utm_campaign=cli), signed in with the same account, so the people you work with don't need a terminal. The website adds what a team shares:
+
+- **Your crew**: invite people by email under **People**; they see the same boards, risks and roadmap, and their changes reach your terminal within seconds.
+- **Status for others**: the weekly brief, a one-click status report, and read-only links for stakeholders.
+- **Intake forms**: a public form that drops requests onto a project's board.
+- **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
 
 npm doesn't update a global install by itself, so once a day `harbor` asks npm whether a newer version is out, alongside whatever command you ran, and says so in one line when there is (`npm install -g @harborppm/cli@latest` updates it). It says nothing in scripts, pipes or CI; set `HARBOR_NO_UPDATE_CHECK=1` (or `NO_UPDATE_NOTIFIER=1`) to turn it off.
@@ -51,8 +67,6 @@ npm doesn't update a global install by itself, so once a day `harbor` asks npm w
 
 Task titles, names and notes can come from an intake form, a GitHub pull request or anyone in a harbor. Before the commands or the app show them, `harbor` takes out the control characters a terminal would act on (escape sequences, backspaces, text-direction overrides), so a title can't set your clipboard, retitle the window or hide what's around it. `--json` keeps the data exact, with those characters written as `\u` escapes.
 
-It runs on the same engine as the website: health, task keys, limits and undo work the same way, changes save as you go (the header says when, and holds them while you're offline), and changes anyone makes on the website or elsewhere show up within a couple of seconds. It needs full access, which `harbor login` asks for by name; an older sign-in is asked again the first time.
-
 ## Signing in
 
 `harbor signup` is for a first visit: the same sign-in, with the page opened on making an account. `harbor login` registers the CLI with Harbor and opens the same page Claude and other apps use: it names "Harbor CLI" and asks what to allow. Choose **Allow reading only** (or run `harbor login --read-only`) if it shouldn't change anything. The sign-in is saved in `~/.config/harbor/credentials.json`, readable only by you, and refreshes itself for 30 days.
@@ -68,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.0",
+  "version": "0.11.0",
   "description": "Harbor from the terminal: a full-screen app with everything, plus commands for scripts and agents.",
   "keywords": [
     "harbor",