@harborppm/cli 0.6.0 → 0.7.0

package/README.md

@@ -10,6 +10,18 @@ harbor mine                     # or one command at a time
 
 Needs Node 22 or later.
 
+## New to Harbor?
+
+You can start from the terminal. Harbor is free to start.
+
+```sh
+npm install -g @harborppm/cli
+harbor signup      # make your account in the browser (email or Google), then come back
+harbor             # name your harbor and its first project, and you're in
+```
+
+`harbor signup` opens Harbor's page on **Create**; confirm your email from the letter it sends when you get a moment. The first time you run `harbor` with no harbor yet, it asks for a name (Enter takes a suggestion) and, if you like, a first project, then opens on it. Joining a team's harbor instead? Open the invite they sent you, and `harbor` opens on their harbor.
+
 ## The full-screen app
 
 `harbor` on its own takes over the terminal, like `htop` or `lazygit`, and gives it back when you press `q`. It opens on Harbor's mark (the teal tile, the H and three boats, drawn in half blocks) while your harbor loads; after that the sidebar holds just the screens. Then:
@@ -43,7 +55,7 @@ It runs on the same engine as the website: health, task keys, limits and undo wo
 
 ## 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 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.
 
 `harbor logout` forgets it on this machine. To end its access everywhere, disconnect **Harbor CLI** under **Connected apps** in Harbor's menu.
 

package/dist/app.mjs

@@ -1,4 +1,5 @@
 // Built from src/tui by cli/build.mjs. Edit the source, not this file.
+import { createInterface } from "node:readline/promises";
 import { Box, Text, render, useApp, useInput, useWindowSize } from "ink";
 import React, { createContext, useContext, useEffect, useMemo, useState } from "react";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
@@ -8695,7 +8696,8 @@ function plainTransport(t) {
 		load: async (workspaceId) => plainDeep(await t.load(workspaceId)),
 		save: async (body) => plainDeep(await t.save(body)),
 		wait: async (workspaceId, since) => plainDeep(await t.wait(workspaceId, since)),
-		history: async (query) => plainDeep(await t.history(query))
+		history: async (query) => plainDeep(await t.history(query)),
+		create: async (name) => plainDeep(await t.create(name))
 	};
 }
 /** Harbor said no, or couldn't be reached (`offline`). */
@@ -8753,6 +8755,10 @@ function httpTransport(source, fetcher = fetch) {
 		history: (history) => post({
 			op: "history",
 			history
+		}),
+		create: (name) => post({
+			op: "create",
+			name
 		})
 	};
 }
@@ -9030,6 +9036,47 @@ function createUiStore() {
 	}));
 }
 
+//#endregion
+//#region src/lib/empty.ts
+/** What a new harbor is called until its owner names it: "Sam's harbor". */
+function suggestedHarborName(displayName, email) {
+	const first = (displayName || email || "").split(/[\s@]/)[0]?.trim();
+	if (!first) return "My harbor";
+	return `${first}'s harbor`;
+}
+
+//#endregion
+//#region src/tui/first-run.ts
+/**
+* A new account's first `harbor`: it isn't in a harbor yet, so the terminal
+* asks for a name (and, if they like, a first project) and makes the same
+* empty harbor the website's launch page makes, instead of sending them off
+* to the website.
+*/
+async function firstHarbor(deps) {
+	const fallback = suggestedHarborName(deps.account.name, deps.account.email);
+	deps.say("You're signed in, but you aren't in a harbor yet, so let's make yours.");
+	deps.say("Joining a team's harbor instead? Open the invite they sent you.\n");
+	const name = (await deps.ask(`Name your harbor (Enter for "${fallback}"): `)).trim() || fallback;
+	const project = (await deps.ask("Name your first project (Enter to skip): ")).trim() || null;
+	const { harbor } = await deps.transport.create(name.slice(0, 120));
+	return {
+		harbor,
+		project: project?.slice(0, 120) ?? null
+	};
+}
+/** The first project, in the new harbor's starter program, led by its owner. */
+function addFirstProject(store, name, accountId, today) {
+	const s = store.getState();
+	const program = s.programs[0];
+	if (!program) return null;
+	const me = s.people.find((p) => p.accountId === accountId) ?? s.people[0];
+	return commitCreate(store, "project", {
+		name,
+		ownerId: me?.id ?? ""
+	}, { programId: program.id }, today);
+}
+
 //#endregion
 //#region src/tui/main.tsx
 /**
@@ -9072,6 +9119,11 @@ async function startApp(deps, options = {}) {
 		instance.unmount();
 		throw err;
 	}
+	if (deps.firstRun) {
+		const project = deps.firstRun.project;
+		if (project) addFirstProject(store, project, account.id, today());
+		ui.setState({ notice: project ? `Your harbor is ready, with ${project} in it. n adds more, ? lists the keys.` : "Your harbor is ready. n adds a project, ? lists the keys." });
+	}
 	instance.rerender(/* @__PURE__ */ jsx(DepsProvider, {
 		value: {
 			store,
@@ -9113,18 +9165,58 @@ function harborNamed(harbors, key) {
 async function runApp(opts) {
 	const theme = await pickTheme(opts.theme);
 	const transport = httpTransport(opts.source, opts.fetcher);
-	const { account, harbors } = await transport.harbors();
-	if (harbors.length === 0) throw new HarborError(`You don't belong to a harbor yet. Make one at ${opts.source.server} first.`);
+	const answer = await transport.harbors();
+	const account = answer.account;
+	let harbors = answer.harbors;
+	let firstRun;
+	let workspaceId;
+	if (harbors.length === 0) {
+		const terminal = terminalAsk();
+		try {
+			const made = await firstHarbor({
+				ask: terminal.ask,
+				say: (line) => process.stdout.write(`${line}\n`),
+				transport: plainTransport(transport),
+				account: plainDeep(account)
+			});
+			harbors = [made.harbor];
+			workspaceId = made.harbor.id;
+			firstRun = { project: made.project };
+		} finally {
+			terminal.close();
+		}
+	} else if (opts.harbor) workspaceId = harborNamed(harbors, opts.harbor).id;
 	const { instance } = await startApp({
 		transport,
 		account,
 		harbors,
-		workspaceId: (opts.harbor ? harborNamed(harbors, opts.harbor) : void 0)?.id,
+		workspaceId,
 		splashMs: SPLASH_MS,
-		theme
+		theme,
+		firstRun
 	}, { alternateScreen: true });
 	await instance.waitUntilExit();
 }
+/** Questions asked on the plain terminal, before the app takes it over. Ctrl+C stops. */
+function terminalAsk() {
+	const rl = createInterface({
+		input: process.stdin,
+		output: process.stdout
+	});
+	let stop = () => {};
+	const stopped = new Promise((_, reject) => stop = reject);
+	stopped.catch(() => {});
+	const nothing = () => stop(new HarborError("Stopped. Nothing was made."));
+	rl.on("SIGINT", nothing);
+	rl.on("close", nothing);
+	return {
+		ask: (question) => Promise.race([rl.question(question), stopped]),
+		close: () => {
+			rl.off("close", nothing);
+			rl.close();
+		}
+	};
+}
 
 //#endregion
-export { SPLASH_MS, TransportError, harborNamed, httpTransport, runApp, startApp };
+export { SPLASH_MS, TransportError, firstHarbor, harborNamed, httpTransport, runApp, startApp };

package/lib/auth.mjs

@@ -90,9 +90,16 @@ export async function listenForCode(state, { timeoutMs = 5 * 60_000 } = {}) {
 
 /**
  * The whole sign-in. `open(url)` shows the asking page (a browser, or a test
- * driving one). Returns credentials to save.
+ * driving one). `signUp` opens it on making an account. Returns credentials to save.
  */
-export async function login({ server, readOnly = false, open, fetcher = fetch, now = Date.now }) {
+export async function login({
+  server,
+  readOnly = false,
+  signUp = false,
+  open,
+  fetcher = fetch,
+  now = Date.now,
+}) {
   const meta = await discover(server, fetcher);
   const state = b64url(randomBytes(16));
   const { verifier, challenge } = pkcePair();
@@ -122,6 +129,8 @@ export async function login({ server, readOnly = false, open, fetcher = fetch, n
     code_challenge: challenge,
     code_challenge_method: "S256",
     scope: readOnly ? "openid offline_access" : `openid offline_access ${WRITE_SCOPE} ${APP_SCOPE}`,
+    // OpenID's way to say "new here": Harbor's page opens on Create.
+    ...(signUp ? { prompt: "create" } : {}),
   }).toString();
   await open(authorize.toString());
 

package/lib/cli.mjs

@@ -24,6 +24,7 @@ import { jsonText, plain } from "./plain.mjs";
 export const HELP = `harbor: Harbor from the terminal
 
   harbor                                      the full-screen app: everything, with the keyboard
+  harbor signup [--server URL]                new to Harbor: make an account (opens your browser)
   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
@@ -174,6 +175,10 @@ export function hint(message) {
     .replace(
       /^Say which project or program it belongs to\.$/,
       "Say where it belongs: --project NAME or --program NAME.",
+    )
+    .replace(
+      /^You don't belong to a harbor yet\..*$/s,
+      "You aren't in a harbor yet. Run harbor to make one, or open the invite a team sent you.",
     );
 }
 
@@ -193,7 +198,7 @@ export function commandHelp(command) {
       picked.push(lines[++i]);
   }
   if (picked.length === 0) return null;
-  const common = ["login", "logout", "use", "theme", "help", "app"].includes(command)
+  const common = ["signup", "login", "logout", "use", "theme", "help", "app"].includes(command)
     ? []
     : ["", "  Also takes --json, and --harbor NAME when you're in more than one harbor."];
   return [...picked, ...common].join("\n");
@@ -300,8 +305,12 @@ export async function run(argv, io = {}) {
     return 0;
   }
 
-  if (command === "login") {
-    const { values } = parseArgs(rest, { flags: ["read-only"], options: ["server"] });
+  if (command === "login" || command === "signup") {
+    const signUp = command === "signup";
+    const { values } = parseArgs(rest, {
+      flags: signUp ? [] : ["read-only"],
+      options: ["server"],
+    });
     const server = (values.server ?? env.HARBOR_SERVER ?? DEFAULT_SERVER).replace(/\/$/, "");
     if (!/^https?:\/\/[^/]/.test(server) || !URL.canParse(server)) {
       throw new HarborError(`--server needs a web address, like ${DEFAULT_SERVER}.`);
@@ -310,11 +319,16 @@ export async function run(argv, io = {}) {
     const creds = await login({
       server,
       readOnly: Boolean(values["read-only"]),
+      signUp,
       fetcher,
       open:
         io.open ??
         ((url) => {
-          out(`Opening your browser to sign in. If it doesn't open, go to:\n\n  ${url}\n`);
+          out(
+            signUp
+              ? `Opening your browser to make your Harbor account. If it doesn't open, go to:\n\n  ${url}\n`
+              : `Opening your browser to sign in (new to Harbor? choose Create there). If it doesn't open, go to:\n\n  ${url}\n`,
+          );
           openBrowser(url);
         }),
     });
@@ -326,14 +340,16 @@ export async function run(argv, io = {}) {
     await writeCredentials(creds, env);
     const canWrite = creds.scope.split(" ").includes("harbor:write");
     const said = `Signed in to ${server}${canWrite ? "." : ", reading only."}`;
+    const next = signUp ? "Next: run harbor, and it helps you make your first harbor." : null;
     const welcome = banner(io, env, ({ bold, dim }) => [
       bold("Welcome aboard."),
       said,
+      ...(next ? [next] : []),
       "",
       dim("harbor        the full-screen app"),
       dim("harbor help   every command"),
     ]);
-    out(welcome ?? said);
+    out(welcome ?? (next ? `${said}\n${next}` : said));
     return 0;
   }
 
@@ -367,7 +383,8 @@ export async function run(argv, io = {}) {
   }
 
   const creds = await readCredentials(env);
-  if (!creds) throw new HarborError("Not signed in. Run harbor login.");
+  if (!creds)
+    throw new HarborError("Not signed in. Run harbor login, or harbor signup if you're new.");
   const client = createClient({ creds, save: (c) => writeCredentials(c, env), fetcher });
   const opts = { today: todayLocal() };
 

package/lib/format.mjs

@@ -52,7 +52,7 @@ export function taskList(r, opts) {
 
 export function harbors(r) {
   const list = r.harbors ?? [];
-  if (!list.length) return "You aren't in any harbor yet.";
+  if (!list.length) return "You aren't in any harbor yet. Run harbor to make one.";
   return list.map((h) => `${h.id}  ${h.name}${h.role ? `  (${h.role})` : ""}`).join("\n");
 }
 

package/package.json

@@ -1,7 +1,19 @@
 {
   "name": "@harborppm/cli",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Harbor from the terminal: a full-screen app with everything, plus commands for scripts and agents.",
+  "keywords": [
+    "harbor",
+    "project-management",
+    "portfolio-management",
+    "ppm",
+    "kanban",
+    "tasks",
+    "cli",
+    "tui",
+    "terminal",
+    "mcp"
+  ],
   "type": "module",
   "bin": {
     "harbor": "bin/harbor.mjs"