@harborppm/cli 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Harbor
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,53 @@
-# Temporary Holding Version
+# Harbor CLI
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[Harbor](https://harborppm.com) from the terminal: what's on you, add and finish tasks, comment, check in, log risks.
+
+```sh
+npx @harborppm/cli login        # opens your browser once
+npx @harborppm/cli mine
+```
+
+Or install it: `npm install -g @harborppm/cli`, then `harbor mine`. Needs Node 20 or later.
+
+## Signing in
+
+`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.
+
+`harbor logout` forgets it on this machine. To end its access everywhere, disconnect **Harbor CLI** under **Connected apps** in Harbor's menu.
+
+## Commands
+
+```
+harbor harbors                              the harbors you belong to
+harbor mine                                 what's on you, late first
+harbor tasks [words] [--project P] [--assignee me|NAME] [--late] [--status S]
+harbor show TASK                            one task in full
+
+harbor add "TITLE" --project P [--assignee me|NAME] [--due YYYY-MM-DD]
+                   [--priority low|medium|high|urgent] [--status S]
+harbor start TASK | review TASK | done TASK [--confirm]
+harbor edit TASK [--title T] [--assignee me|none|NAME] [--due DATE|none]
+                 [--priority P] [--status S]
+harbor comment TASK "TEXT"
+harbor checkin "WHAT YOU'RE DOING" [--on-blocker]
+harbor risk "TITLE" [--project P] [--impact 1-5] [--probability 1-5]
+harbor issue "TITLE" [--project P]
+```
+
+Every command takes `--harbor NAME` when you're in more than one, and `--json` for the raw result. Statuses are backlog, todo, doing, review and done.
+
+Harbor holds back what it would hold back in the app: finishing a task that still waits on another, or going past a column's limit. The CLI says so and names the flag that goes ahead (`--confirm`, `--over-limit`).
+
+Every change shows in Harbor's History as yours, "via Harbor CLI". Nothing the CLI does deletes anything.
+
+## Another server
+
+`harbor login --server https://your-harbor.example` (or `HARBOR_SERVER`). `HARBOR_CONFIG_DIR` moves the saved sign-in.
+
+## Developing
+
+No dependencies. `npm test` runs the CLI's tests against a stand-in Harbor; `e2e/cli.test.mjs` in the repository drives it against a real one.
+
+## License
+
+MIT (see `LICENSE`). The rest of the Harbor repository is private.

package/bin/harbor.mjs

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+import { run } from "../lib/cli.mjs";
+import { HarborError } from "../lib/mcp.mjs";
+
+run(process.argv.slice(2)).then(
+  (code) => process.exit(code),
+  (err) => {
+    const known =
+      err instanceof HarborError ||
+      /^(Unknown option|--\S+ (needs|takes|is))/.test(err?.message ?? "");
+    process.stderr.write(
+      `${known ? err.message : `Something went wrong: ${err?.message ?? err}`}\n`,
+    );
+    process.exit(1);
+  },
+);

package/lib/args.mjs

@@ -0,0 +1,34 @@
+/**
+ * A small argument reader: positionals, `--flag`, `--key value` and
+ * `--key=value`. Unknown flags are an error, so a typo doesn't quietly do
+ * something else.
+ */
+export function parseArgs(argv, { flags = [], options = [] } = {}) {
+  const positionals = [];
+  const values = {};
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--") {
+      positionals.push(...argv.slice(i + 1));
+      break;
+    }
+    if (!arg.startsWith("--") || arg === "--") {
+      positionals.push(arg);
+      continue;
+    }
+    const [key, inline] = arg.slice(2).split(/=(.*)/s, 2);
+    if (flags.includes(key)) {
+      if (inline !== undefined) throw new Error(`--${key} takes no value.`);
+      values[key] = true;
+    } else if (options.includes(key)) {
+      const value = inline ?? argv[++i];
+      if (value === undefined || (inline === undefined && value.startsWith("--"))) {
+        throw new Error(`--${key} needs a value.`);
+      }
+      values[key] = value;
+    } else {
+      throw new Error(`Unknown option --${key}.`);
+    }
+  }
+  return { positionals, values };
+}

package/lib/auth.mjs

@@ -0,0 +1,170 @@
+/**
+ * Signing in: OAuth 2.1 with PKCE against Harbor's authorization server, as
+ * any MCP app does. The CLI registers itself, opens the browser at Harbor's
+ * asking page and listens on 127.0.0.1 for the answer.
+ */
+import { createHash, randomBytes } from "node:crypto";
+import { createServer } from "node:http";
+
+export const CLIENT_NAME = "Harbor CLI";
+export const WRITE_SCOPE = "harbor:write";
+
+const b64url = (buf) => Buffer.from(buf).toString("base64url");
+
+export function pkcePair() {
+  const verifier = b64url(randomBytes(32));
+  const challenge = b64url(createHash("sha256").update(verifier).digest());
+  return { verifier, challenge };
+}
+
+async function json(res, what) {
+  const text = await res.text();
+  let body = null;
+  try {
+    body = JSON.parse(text);
+  } catch {
+    // Not JSON: say what came back below.
+  }
+  if (!res.ok) {
+    const why = body?.error_description || body?.error || text.slice(0, 200) || res.statusText;
+    throw new Error(`${what} failed (${res.status}): ${why}`);
+  }
+  return body;
+}
+
+/** The server's OAuth endpoints, from its discovery document. */
+export async function discover(server, fetcher = fetch) {
+  const res = await fetcher(new URL("/.well-known/oauth-authorization-server", server));
+  return json(res, "Finding Harbor's sign-in");
+}
+
+/**
+ * Wait for the browser to come back to http://127.0.0.1:<port>/callback.
+ * Resolves with { redirectUri, code: Promise<string> } once listening.
+ */
+export async function listenForCode(state, { timeoutMs = 5 * 60_000 } = {}) {
+  let settle;
+  const code = new Promise((resolve, reject) => (settle = { resolve, reject }));
+  const server = createServer((req, res) => {
+    const url = new URL(req.url ?? "/", "http://127.0.0.1");
+    if (url.pathname !== "/callback") {
+      res.writeHead(404).end();
+      return;
+    }
+    const error = url.searchParams.get("error");
+    const ok = !error && url.searchParams.get("state") === state && url.searchParams.get("code");
+    res.writeHead(ok ? 200 : 400, { "content-type": "text/html; charset=utf-8" });
+    res.end(
+      `<!doctype html><meta charset="utf-8"><title>Harbor CLI</title><body style="font:16px system-ui;margin:3rem">` +
+        (ok
+          ? "<h1>You're signed in</h1><p>Go back to your terminal.</p>"
+          : `<h1>Not signed in</h1><p>${error === "access_denied" ? "You declined." : "Something didn't match. Run harbor login again."}</p>`) +
+        "</body>",
+    );
+    if (ok) settle.resolve(url.searchParams.get("code"));
+    else
+      settle.reject(
+        new Error(
+          error === "access_denied"
+            ? "You declined in the browser."
+            : "The sign-in didn't come back as expected.",
+        ),
+      );
+  });
+  await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
+  const { port } = server.address();
+  const timer = setTimeout(
+    () => settle.reject(new Error("No answer from the browser in 5 minutes.")),
+    timeoutMs,
+  );
+  const done = code.finally(() => {
+    clearTimeout(timer);
+    server.close();
+  });
+  done.catch(() => {});
+  return { redirectUri: `http://127.0.0.1:${port}/callback`, code: done };
+}
+
+/**
+ * The whole sign-in. `open(url)` shows the asking page (a browser, or a test
+ * driving one). Returns credentials to save.
+ */
+export async function login({ server, readOnly = false, open, fetcher = fetch, now = Date.now }) {
+  const meta = await discover(server, fetcher);
+  const state = b64url(randomBytes(16));
+  const { verifier, challenge } = pkcePair();
+  const { redirectUri, code } = await listenForCode(state);
+
+  const client = await json(
+    await fetcher(meta.registration_endpoint, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({
+        client_name: CLIENT_NAME,
+        redirect_uris: [redirectUri],
+        grant_types: ["authorization_code", "refresh_token"],
+        response_types: ["code"],
+        token_endpoint_auth_method: "none",
+      }),
+    }),
+    "Registering the CLI",
+  );
+
+  const authorize = new URL(meta.authorization_endpoint);
+  authorize.search = new URLSearchParams({
+    response_type: "code",
+    client_id: client.client_id,
+    redirect_uri: redirectUri,
+    state,
+    code_challenge: challenge,
+    code_challenge_method: "S256",
+    scope: readOnly ? "openid offline_access" : `openid offline_access ${WRITE_SCOPE}`,
+  }).toString();
+  await open(authorize.toString());
+
+  const tokens = await json(
+    await fetcher(meta.token_endpoint, {
+      method: "POST",
+      headers: { "content-type": "application/x-www-form-urlencoded" },
+      body: new URLSearchParams({
+        grant_type: "authorization_code",
+        code: await code,
+        redirect_uri: redirectUri,
+        client_id: client.client_id,
+        code_verifier: verifier,
+      }),
+    }),
+    "Finishing sign-in",
+  );
+  return toCredentials(server, meta.token_endpoint, client.client_id, tokens, now());
+}
+
+export function toCredentials(server, tokenEndpoint, clientId, tokens, at) {
+  return {
+    server,
+    tokenEndpoint,
+    clientId,
+    accessToken: tokens.access_token,
+    refreshToken: tokens.refresh_token ?? null,
+    expiresAt: at + (tokens.expires_in ?? 3600) * 1000,
+    scope: tokens.scope ?? "",
+  };
+}
+
+/** New tokens from the refresh token; the old one stops working. */
+export async function refresh(creds, { fetcher = fetch, now = Date.now } = {}) {
+  if (!creds.refreshToken) throw new Error("Signed out. Run harbor login.");
+  const tokens = await json(
+    await fetcher(creds.tokenEndpoint, {
+      method: "POST",
+      headers: { "content-type": "application/x-www-form-urlencoded" },
+      body: new URLSearchParams({
+        grant_type: "refresh_token",
+        refresh_token: creds.refreshToken,
+        client_id: creds.clientId,
+      }),
+    }),
+    "Refreshing your sign-in",
+  );
+  return toCredentials(creds.server, creds.tokenEndpoint, creds.clientId, tokens, now());
+}

package/lib/cli.mjs

@@ -0,0 +1,314 @@
+/**
+ * The commands. `run(argv, io)` is the whole CLI with its outside world
+ * passed in (output, the browser, fetch, where credentials live), so tests
+ * drive it without a terminal.
+ */
+import { spawn } from "node:child_process";
+import { parseArgs } from "./args.mjs";
+import { login } from "./auth.mjs";
+import { DEFAULT_SERVER, forgetCredentials, readCredentials, writeCredentials } from "./config.mjs";
+import { harbors, myWork, taskLine, taskList, todayLocal } from "./format.mjs";
+import { HarborError, createClient } from "./mcp.mjs";
+
+export const HELP = `harbor: Harbor from the terminal
+
+  harbor login [--server URL] [--read-only]   sign in (opens your browser once)
+  harbor logout                               forget the sign-in on this machine
+  harbor harbors                              the harbors you belong to
+
+  harbor mine                                 what's on you, late first
+  harbor tasks [words] [--project P] [--assignee me|NAME] [--late] [--status S]
+  harbor show TASK                            one task in full (TASK: its key, RR-42, or id)
+
+  harbor add "TITLE" --project P [--assignee me|NAME] [--due YYYY-MM-DD]
+                     [--priority low|medium|high|urgent] [--status S]
+  harbor start TASK | review TASK | done TASK [--confirm]
+  harbor edit TASK [--title T] [--assignee me|none|NAME] [--due DATE|none]
+                   [--priority P] [--status S]
+  harbor comment TASK "TEXT"
+  harbor checkin "WHAT YOU'RE DOING" [--on-blocker]
+  harbor risk "TITLE" [--project P] [--impact 1-5] [--probability 1-5]
+  harbor issue "TITLE" [--project P]
+
+  Every command takes --harbor NAME (when you're in more than one) and --json.
+  Statuses: backlog, todo, doing, review, done.
+  Changes show in Harbor's History as yours, "via Harbor CLI". Nothing here deletes.
+`;
+
+const COMMON = { flags: ["json", "help"], options: ["harbor"] };
+const spec = (flags = [], options = []) => ({
+  flags: [...COMMON.flags, ...flags],
+  options: [...COMMON.options, ...options],
+});
+
+function openBrowser(url) {
+  const [cmd, args] =
+    process.platform === "darwin"
+      ? ["open", [url]]
+      : process.platform === "win32"
+        ? ["cmd", ["/c", "start", "", url]]
+        : ["xdg-open", [url]];
+  try {
+    spawn(cmd, args, { stdio: "ignore", detached: true })
+      .on("error", () => {})
+      .unref();
+  } catch {
+    // No browser to open: the printed address is enough.
+  }
+}
+
+const one = (positionals, what) => {
+  if (positionals.length !== 1) throw new HarborError(`Give one ${what}.`);
+  return positionals[0];
+};
+const text = (positionals, what) => {
+  const s = positionals.join(" ").trim();
+  if (!s) throw new HarborError(`Say ${what}.`);
+  return s;
+};
+const level = (v, name) => {
+  if (v === undefined) return undefined;
+  const n = Number(v);
+  if (!Number.isInteger(n) || n < 1 || n > 5) throw new HarborError(`--${name} is 1 to 5.`);
+  return n;
+};
+const nullable = (v) => (v === "none" ? null : v);
+
+/** Harbor's refusals are worded for agents; say which flag answers them. */
+export function hint(message) {
+  const said = message.replace(/\s*Ask the person;.*$/s, "");
+  if (/confirmed: true/.test(message))
+    return `${said}\nTo finish it anyway, run it again with --confirm.`;
+  if (/overLimit: true/.test(message))
+    return `${said}\nTo go past the limit, run it again with --over-limit.`;
+  return message;
+}
+
+export async function run(argv, io = {}) {
+  const out = io.out ?? ((s) => process.stdout.write(`${s}\n`));
+  const env = io.env ?? process.env;
+  const fetcher = io.fetch ?? fetch;
+  const [command, ...rest] = argv;
+
+  if (!command || command === "help" || command === "--help" || command === "-h") {
+    out(HELP);
+    return 0;
+  }
+
+  if (command === "login") {
+    const { values } = parseArgs(rest, { flags: ["read-only"], options: ["server"] });
+    const server = (values.server ?? env.HARBOR_SERVER ?? DEFAULT_SERVER).replace(/\/$/, "");
+    const creds = await login({
+      server,
+      readOnly: Boolean(values["read-only"]),
+      fetcher,
+      open:
+        io.open ??
+        ((url) => {
+          out(`Opening your browser to sign in. If it doesn't open, go to:\n\n  ${url}\n`);
+          openBrowser(url);
+        }),
+    });
+    await writeCredentials(creds, env);
+    const canWrite = creds.scope.split(" ").includes("harbor:write");
+    out(`Signed in to ${server}${canWrite ? "." : ", reading only."}`);
+    return 0;
+  }
+
+  if (command === "logout") {
+    await forgetCredentials(env);
+    out(
+      "Signed out on this machine. To end its access everywhere, disconnect Harbor CLI under Connected apps in Harbor's menu.",
+    );
+    return 0;
+  }
+
+  const creds = await readCredentials(env);
+  if (!creds) throw new HarborError("Not signed in. Run harbor login.");
+  const client = createClient({ creds, save: (c) => writeCredentials(c, env), fetcher });
+  const opts = { today: todayLocal() };
+
+  const call = async (name, args, show) => {
+    const result = await client.call(name, args).catch((err) => {
+      if (err instanceof HarborError) throw new HarborError(hint(err.message));
+      throw err;
+    });
+    out(asJson ? JSON.stringify(result, null, 2) : show(result));
+    return 0;
+  };
+  let asJson = false;
+  const parse = (s) => {
+    const p = parseArgs(rest, s);
+    asJson = Boolean(p.values.json);
+    return { ...p, harbor: p.values.harbor };
+  };
+
+  switch (command) {
+    case "harbors": {
+      parse(spec());
+      return call("list_harbors", {}, harbors);
+    }
+    case "mine": {
+      const { harbor } = parse(spec());
+      return call("my_work", { harbor }, (r) => myWork(r, opts));
+    }
+    case "tasks": {
+      const { positionals, values, harbor } = parse(
+        spec(["late"], ["project", "assignee", "status"]),
+      );
+      return call(
+        "search_tasks",
+        {
+          harbor,
+          query: positionals.join(" ") || undefined,
+          project: values.project,
+          assignee: values.assignee,
+          status: values.status ? values.status.split(",") : undefined,
+          overdue: values.late || undefined,
+        },
+        (r) => taskList(r, opts),
+      );
+    }
+    case "show": {
+      const { positionals, harbor } = parse(spec());
+      return call("get_task", { harbor, task: one(positionals, "task id") }, (t) => {
+        const lines = [
+          taskLine(
+            { ...t, waitingOn: t.waitingOn.filter((w) => w.status !== "done").length },
+            opts,
+          ),
+        ];
+        if (t.description) lines.push("", t.description);
+        if (t.checklist.length)
+          lines.push("", ...t.checklist.map((c) => `  [${c.done ? "x" : " "}] ${c.step}`));
+        if (t.waitingOn.length)
+          lines.push(
+            "",
+            "Waits on:",
+            ...t.waitingOn.map((w) => `  ${w.key ?? w.id}  ${w.title} (${w.status})`),
+          );
+        if (t.waitedOnBy.length)
+          lines.push(
+            "",
+            "Holds up:",
+            ...t.waitedOnBy.map((w) => `  ${w.key ?? w.id}  ${w.title} (${w.status})`),
+          );
+        if (t.comments.length)
+          lines.push(
+            "",
+            ...t.comments.map((c) => `${c.author ?? "Someone"}, ${c.at.slice(0, 10)}: ${c.body}`),
+          );
+        return lines.join("\n");
+      });
+    }
+    case "add": {
+      const { positionals, values, harbor } = parse(
+        spec(["over-limit"], ["project", "assignee", "due", "priority", "status"]),
+      );
+      if (!values.project) throw new HarborError("Say which project: --project NAME.");
+      return call(
+        "create_task",
+        {
+          harbor,
+          project: values.project,
+          title: text(positionals, "the task"),
+          assignee: values.assignee,
+          due: values.due,
+          priority: values.priority,
+          status: values.status,
+          overLimit: values["over-limit"] || undefined,
+        },
+        (r) => `Added: ${taskLine(r.created, opts)}`,
+      );
+    }
+    case "start":
+    case "review":
+    case "done": {
+      const { positionals, values, harbor } = parse(spec(["confirm", "over-limit"]));
+      const status = { start: "doing", review: "review", done: "done" }[command];
+      return call(
+        "update_task",
+        {
+          harbor,
+          task: one(positionals, "task id"),
+          status,
+          confirmed: values.confirm || undefined,
+          overLimit: values["over-limit"] || undefined,
+        },
+        (r) =>
+          [
+            `${r.updated.title}: ${{ doing: "started", review: "in review", done: "done" }[status]}.`,
+            r.queuedNext ? `Next one: ${taskLine(r.queuedNext, opts)}` : "",
+          ]
+            .filter(Boolean)
+            .join("\n"),
+      );
+    }
+    case "edit": {
+      const { positionals, values, harbor } = parse(
+        spec(["confirm", "over-limit"], ["title", "assignee", "due", "priority", "status"]),
+      );
+      return call(
+        "update_task",
+        {
+          harbor,
+          task: one(positionals, "task id"),
+          title: values.title,
+          assignee: values.assignee,
+          due: values.due === undefined ? undefined : nullable(values.due),
+          priority: values.priority,
+          status: values.status,
+          confirmed: values.confirm || undefined,
+          overLimit: values["over-limit"] || undefined,
+        },
+        (r) => `Updated: ${taskLine(r.updated, opts)}`,
+      );
+    }
+    case "comment": {
+      const { positionals, harbor } = parse(spec());
+      const [task, ...words] = positionals;
+      if (!task) throw new HarborError("Give a task id, then the comment.");
+      return call(
+        "add_comment",
+        { harbor, task, body: text(words, "the comment") },
+        (r) =>
+          `Comment added to ${r.commented.task}${r.mentioned?.length ? `; told ${r.mentioned.join(", ")}` : ""}.`,
+      );
+    }
+    case "checkin": {
+      const { positionals, values, harbor } = parse(spec(["on-blocker"]));
+      return call(
+        "check_in",
+        {
+          harbor,
+          note: text(positionals, "what you're doing"),
+          onBlocker: Boolean(values["on-blocker"]),
+        },
+        () => "Checked in for today.",
+      );
+    }
+    case "risk":
+    case "issue": {
+      const { positionals, values, harbor } = parse(
+        spec([], ["project", "program", "owner", "impact", "probability", "due"]),
+      );
+      return call(
+        "log_raid",
+        {
+          harbor,
+          kind: command,
+          title: text(positionals, `the ${command}`),
+          project: values.project,
+          program: values.program,
+          owner: values.owner,
+          impact: level(values.impact, "impact"),
+          probability: command === "risk" ? level(values.probability, "probability") : undefined,
+          due: values.due,
+        },
+        (r) => `Logged the ${command} (${r.raised.id}).`,
+      );
+    }
+    default:
+      throw new HarborError(`No command "${command}". Run harbor help.`);
+  }
+}

package/lib/config.mjs

@@ -0,0 +1,37 @@
+/**
+ * Where the CLI keeps its sign-in: one JSON file per machine, readable only
+ * by its owner. HARBOR_CONFIG_DIR moves it (tests, several accounts).
+ */
+import { chmod, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export const DEFAULT_SERVER = "https://harborppm.com";
+
+export function configDir(env = process.env) {
+  if (env.HARBOR_CONFIG_DIR) return env.HARBOR_CONFIG_DIR;
+  const base = env.XDG_CONFIG_HOME || join(homedir(), ".config");
+  return join(base, "harbor");
+}
+
+const file = (env) => join(configDir(env), "credentials.json");
+
+/** The saved sign-in, or null when there isn't one. */
+export async function readCredentials(env = process.env) {
+  try {
+    return JSON.parse(await readFile(file(env), "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+export async function writeCredentials(creds, env = process.env) {
+  await mkdir(configDir(env), { recursive: true, mode: 0o700 });
+  await writeFile(file(env), JSON.stringify(creds, null, 2), { mode: 0o600 });
+  // writeFile keeps an existing file's mode; make sure it's private.
+  await chmod(file(env), 0o600);
+}
+
+export async function forgetCredentials(env = process.env) {
+  await rm(file(env), { force: true });
+}

package/lib/format.mjs

@@ -0,0 +1,62 @@
+/** Plain text for a terminal: one task per line, its key (or id) first so it can be copied. */
+
+const STATUS = {
+  backlog: "backlog",
+  todo: "to do",
+  doing: "doing",
+  review: "review",
+  done: "done",
+};
+
+/** `mine` leaves out whose each task is: every one is yours. */
+export function taskLine(t, { today, mine = false } = {}) {
+  const late = t.due && today && t.due < today && t.status !== "done";
+  const bits = [
+    STATUS[t.status] ?? t.status,
+    t.due ? (late ? `late, due ${t.due}` : `due ${t.due}`) : null,
+    t.priority && t.priority !== "medium" ? t.priority : null,
+    mine ? null : (t.assignee ?? null),
+    t.project ?? null,
+    t.waitingOn ? `waits on ${t.waitingOn}` : null,
+  ].filter(Boolean);
+  return `${t.key ?? t.id}  ${t.title}  (${bits.join(" · ")})`;
+}
+
+export function myWork(w, opts) {
+  if (!w.you) return w.note ?? "Nothing is yours in this harbor yet.";
+  const out = [`${w.you}: ${w.openTasks} open${w.late ? `, ${w.late} late` : ""}`];
+  if (w.tasks?.length) out.push("", ...w.tasks.map((t) => taskLine(t, { ...opts, mine: true })));
+  if (w.waitingOnYou?.length) {
+    out.push("", "Waiting on you:");
+    for (const x of w.waitingOnYou)
+      out.push(
+        `  ${x.theirs.title} (${x.theirs.assignee ?? "unassigned"}) waits on ${x.yourTask.title}`,
+      );
+  }
+  if (w.raid?.length) {
+    out.push("", "Yours in the register:");
+    for (const r of w.raid)
+      out.push(`  ${r.id}  ${r.kind}: ${r.title}${r.due ? ` (review by ${r.due})` : ""}`);
+  }
+  return out.join("\n");
+}
+
+export function taskList(r, opts) {
+  if (!r.tasks?.length) return "No tasks match.";
+  const more =
+    r.total > r.tasks.length
+      ? `\n…and ${r.total - r.tasks.length} more. Narrow it with a word or --project.`
+      : "";
+  return r.tasks.map((t) => taskLine(t, opts)).join("\n") + more;
+}
+
+export function harbors(r) {
+  const list = r.harbors ?? [];
+  if (!list.length) return "You aren't in any harbor yet.";
+  return list.map((h) => `${h.id}  ${h.name}${h.role ? `  (${h.role})` : ""}`).join("\n");
+}
+
+export function todayLocal(d = new Date()) {
+  const p = (n) => String(n).padStart(2, "0");
+  return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())}`;
+}

package/lib/mcp.mjs

@@ -0,0 +1,60 @@
+/**
+ * Calling Harbor's tools: one JSON-RPC `tools/call` per command, over the
+ * same /api/mcp endpoint Claude uses. Tokens last an hour; an expired one is
+ * refreshed once and the call retried.
+ */
+import { refresh } from "./auth.mjs";
+
+export class HarborError extends Error {}
+
+const SKEW_MS = 60_000;
+
+export function createClient({ creds, save, fetcher = fetch, now = Date.now }) {
+  let current = creds;
+  let id = 0;
+
+  async function renew() {
+    current = await refresh(current, { fetcher, now });
+    await save(current);
+  }
+
+  async function post(body) {
+    return fetcher(new URL("/api/mcp", current.server), {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        accept: "application/json, text/event-stream",
+        authorization: `Bearer ${current.accessToken}`,
+      },
+      body: JSON.stringify(body),
+    });
+  }
+
+  return {
+    /** The tool's structured result; a HarborError with Harbor's own words when it says no. */
+    async call(name, args = {}) {
+      if (current.expiresAt - SKEW_MS < now()) await renew();
+      const body = {
+        jsonrpc: "2.0",
+        id: ++id,
+        method: "tools/call",
+        params: { name, arguments: args },
+      };
+      let res = await post(body);
+      if (res.status === 401) {
+        await renew();
+        res = await post(body);
+      }
+      if (res.status === 401) throw new HarborError("Signed out. Run harbor login.");
+      if (res.status === 429)
+        throw new HarborError("Harbor asked to slow down. Try again in a minute.");
+      if (!res.ok) throw new HarborError(`Harbor answered ${res.status}.`);
+      const msg = await res.json();
+      if (msg.error) throw new HarborError(msg.error.message);
+      const result = msg.result ?? {};
+      if (result.isError)
+        throw new HarborError(result.content?.map((c) => c.text).join("\n") || "Harbor said no.");
+      return result.structuredContent ?? JSON.parse(result.content?.[0]?.text ?? "{}");
+    },
+  };
+}

package/package.json

@@ -1,6 +1,23 @@
 {
   "name": "@harborppm/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Harbor from the terminal: what's on you, add and finish tasks, comment, check in, log risks.",
+  "type": "module",
+  "bin": {
+    "harbor": "bin/harbor.mjs"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  },
+  "homepage": "https://harborppm.com/ai",
+  "license": "MIT"
+}