shepherd-onboard 0.1.11 → 0.1.12

package/README.md

@@ -11,7 +11,7 @@ npx -y shepherd-onboard@latest agent
 ```
 
 The command prints the exact prompt the agent should follow, then the exact follow-up commands to open Shepherd WorkOS login/signup, guide Google Workspace Admin Console delegation, open source auth for non-Google sources, open Granola's API key page, finalize, start cloud raw polling/backfills, and install local Messages sync.
-The agent prompt tells coding agents to ask short selection questions first: existing/new org, sources to connect, and Messages skip/provide-handle. If Messages is selected, the agent runs `messages-chats --json`, shows the 20 most recent local Messages chats with contact/group names, and asks which chats to sync. Account creation/relinking always starts with Shepherd WorkOS auth.
+The agent prompt tells coding agents to ask short selection questions first: existing/new org, sources to connect, and Messages skip/provide-handle. If Messages is selected, the agent runs `messages-chats`, opens a minimal local webpage with the 20 most recent local Messages chats, and has the user select which contacts/groups to sync. Account creation/relinking always starts with Shepherd WorkOS auth.
 Existing-organization joins are verified from Shepherd login and company email domain; the typed org name is not trusted by itself.
 
 ## Human Terminal One-liner
@@ -31,7 +31,7 @@ The command:
 - opens Slack authorization
 - opens the Granola desktop app to Settings -> Connectors -> API keys
 - collects the Granola API key after opening the Granola screen when Granola is enabled
-- shows the 20 most recent local Messages chats with contact/group names and only syncs the chats selected by the user
+- opens a minimal local webpage showing the 20 most recent local Messages chats with contact/group names and only syncs the chats selected by the user
 - sets up local macOS Messages raw sync with a background LaunchAgent scoped to the selected chats
 - starts raw polling/backfill for connected sources
 - does not start wiki generation, memory compilation, or doc summaries
@@ -74,12 +74,14 @@ Shepherd must still enforce selected users and groups internally before imperson
 
 ## Messages Chat Selection
 
-List recent local Messages chats:
+Open the local Messages chat selector:
 
 ```sh
-npx -y shepherd-onboard@latest messages-chats --json
+npx -y shepherd-onboard@latest messages-chats
 ```
 
+Use `--json` for machine-readable chat metadata, or `--text` for a terminal list.
+
 Pass the selected chat IDs when finishing onboarding:
 
 ```sh

package/bin/shepherd-onboard.js

@@ -2,6 +2,7 @@
 import { execFile, execFileSync, spawn } from "node:child_process";
 import { mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { createServer } from "node:http";
 import { homedir, platform } from "node:os";
 import { dirname, join } from "node:path";
 import readline from "node:readline";
@@ -312,7 +313,7 @@ async function runAgentOnboarding() {
       googleWorkspaceDelegation: sources.google ? googleWorkspaceDelegationSetup(session.googleWorkspaceDelegation) : undefined,
       granolaApiKeyPage,
       statePath,
-      messagesChatsCommand: sources.messages ? `${agentCommand()} messages-chats --json` : undefined,
+      messagesChatsCommand: sources.messages ? `${agentCommand()} messages-chats` : undefined,
       nextCommand: `${agentCommand()} agent --continue --messages-handle "<phone_or_apple_id>" --messages-chat-ids "<comma_separated_chat_ids>" --granola-api-key "<granola_key>"`,
       needsUserAction: agentNeedsUserAction(sources, opened),
     }, null, 2));
@@ -347,7 +348,7 @@ async function runAgentOnboarding() {
   if (sources.slack) console.log(`${step++}. Ask the user to finish the opened Slack browser authorization.`);
   if (sources.granola) console.log(`${step++}. Ask the user for their Granola API key from the Granola Mac app.`);
   if (sources.messages) {
-    console.log(`${step++}. Run ${agentCommand()} messages-chats --json, ask the user which recent chats to sync, and keep those chat IDs.`);
+    console.log(`${step++}. Run ${agentCommand()} messages-chats, have the user select chats in the browser page, and keep the printed chat IDs.`);
   }
   console.log(`${step++}. Run:`);
   console.log(`   ${agentCommand()} agent --continue --messages-handle "<phone_or_apple_id>" --messages-chat-ids "<comma_separated_chat_ids>" --granola-api-key "<granola_key>"`);
@@ -440,7 +441,7 @@ async function continueAgentOnboarding() {
   if (granolaApiKey) body.granolaApiKey = granolaApiKey;
   if (messagesHandle) body.imessage = { handle: messagesHandle };
   if (state.sources.messages && messagesHandle && selectedMessageChatIds.length === 0) {
-    throw new Error(`Messages sync requires selected chat IDs. Run ${agentCommand()} messages-chats --json, ask the user which chats to sync, then rerun --continue with --messages-chat-ids "<id1>,<id2>".`);
+    throw new Error(`Messages sync requires selected chat IDs. Run ${agentCommand()} messages-chats, have the user select chats in the browser page, then rerun --continue with --messages-chat-ids "<id1>,<id2>".`);
   }
 
   const finalized = await postJson(
@@ -522,6 +523,16 @@ async function runMessagesChatsCommand() {
     return;
   }
 
+  if (!args.text && !args.list) {
+    const selected = await selectChatsInBrowser(chats, { noOpen: Boolean(args["no-open"]) });
+    const selectedIds = selected.map((chat) => chat.chatId).join(",");
+    console.log(`\nSelected ${selected.length} Messages chat(s).`);
+    console.log(`messages-chat-ids=${selectedIds}`);
+    console.log("\nContinue with:");
+    console.log(`  ${agentCommand()} agent --continue --messages-handle "<phone_or_apple_id>" --messages-chat-ids "${selectedIds}"`);
+    return;
+  }
+
   console.log(`\nRecent local Messages chats (${chats.length})\n`);
   for (let i = 0; i < chats.length; i++) {
     console.log(`${String(i + 1).padStart(2, " ")}. ${formatMessageChatOption(chats[i])}`);
@@ -602,7 +613,7 @@ Usage:
   npx -y ${PACKAGE_NAME}@latest agent
   npx -y ${PACKAGE_NAME}@latest agent --login
   npx -y ${PACKAGE_NAME}@latest agent --name <name> --org <organization>
-  npx -y ${PACKAGE_NAME}@latest messages-chats --json
+  npx -y ${PACKAGE_NAME}@latest messages-chats
   npx -y ${PACKAGE_NAME}@latest agent --continue --granola-api-key <key> --messages-handle <value> --messages-chat-ids <ids>
   npx -y ${PACKAGE_NAME}@latest agent --status
   npx -y ${PACKAGE_NAME}@latest granola-api-keys
@@ -637,6 +648,8 @@ Usage:
 
 Options:
   --limit <n>                Number of recent chats to show. Defaults to ${DEFAULT_RECENT_MESSAGE_CHATS}.
+  --text                     Print a terminal list instead of opening the selector page.
+  --no-open                  Print the local selector URL instead of opening it.
   --json                     Print machine-readable chat IDs and labels.
   --help                     Show this help.
 `);
@@ -739,7 +752,7 @@ function printAgentContract() {
       "--granola-api-key \"<granola_key>\" if Granola is being connected",
     ],
     statusCommand: `${command} agent --status`,
-    messagesChatsCommand: `${command} messages-chats --json`,
+    messagesChatsCommand: `${command} messages-chats`,
     googleWorkspaceDelegation: googleWorkspaceDelegationSetup(),
     orgSecurity: "Existing organizations are only reused when Shepherd can verify the authenticated user belongs there, for example by an existing Shepherd account/membership or matching non-personal company email domain. Similar spelling helps match verified orgs, but cannot attach an unverified user to someone else's org.",
     expectedResult: "Cloud sources start raw polling/backfill in the customer-facing Shepherd environment. Local Messages starts via a macOS LaunchAgent when run on macOS. Downstream wiki, memory, and summary compilers remain outside this onboarding flow.",
@@ -785,7 +798,7 @@ If they are joining an existing org, ask for the org name they believe they belo
 If Messages is selected, run:
   ${payload.messagesChatsCommand}
 
-Show the 20 recent local Messages chats to the user as a selection question. Include both DMs and groups, and use the displayed contact/group names. Ask which chats Shepherd should sync. Do not select all chats by default.
+This opens a minimal local webpage with the 20 recent local Messages chats. Have the user select which contacts/groups Shepherd should sync. Do not select all chats by default. When the command returns, keep the printed comma-separated chat IDs.
 
 Then run:
   ${payload.startCommand}
@@ -923,7 +936,7 @@ function agentNeedsUserAction(sources, opened) {
   if (sources.google) actions.push("Have the customer's Google Workspace super admin authorize Shepherd's domain-wide delegation Client ID and scopes in Google Admin Console.");
   if (sources.slack && opened.includes("slack")) actions.push("Complete Slack browser authorization.");
   if (sources.granola) actions.push("Create/copy a Granola API key from the Granola Mac app.");
-  if (sources.messages) actions.push("Run messages-chats, ask the user which recent local Messages chats to sync, then pass the selected chat IDs with the Messages handle.");
+  if (sources.messages) actions.push("Run messages-chats, have the user select local Messages contacts/groups in the browser, then pass the printed chat IDs with the Messages handle.");
   return actions;
 }
 
@@ -1191,7 +1204,7 @@ async function selectRecentMessageChats() {
   }
 
   if (!process.stdin.isTTY) {
-    throw new Error(`Messages sync requires selected chat IDs. Run ${agentCommand()} messages-chats --json and pass --messages-chat-ids "<id1>,<id2>".`);
+    throw new Error(`Messages sync requires selected chat IDs. Run ${agentCommand()} messages-chats and pass --messages-chat-ids "<id1>,<id2>".`);
   }
 
   const chats = await listRecentMessageChats({ limit: DEFAULT_RECENT_MESSAGE_CHATS });
@@ -1199,6 +1212,10 @@ async function selectRecentMessageChats() {
     throw new Error("No recent local Messages chats were found on this Mac.");
   }
 
+  if (!args.text && !args.list) {
+    return selectChatsInBrowser(chats, { noOpen: Boolean(args["no-open"]) });
+  }
+
   console.log(`\nSelect local Messages chats to sync\n`);
   console.log("Shepherd will only pull from the chats you select.");
   for (let i = 0; i < chats.length; i++) {
@@ -1211,6 +1228,356 @@ async function selectRecentMessageChats() {
   return indexes.map((idx) => chats[idx]);
 }
 
+async function selectChatsInBrowser(chats, opts = {}) {
+  if (!chats.length) throw new Error("No recent local Messages chats were found on this Mac.");
+
+  const token = Math.random().toString(36).slice(2) + Math.random().toString(36).slice(2);
+  let settled = false;
+  let server;
+
+  return new Promise((resolve, reject) => {
+    const timeout = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      server?.close();
+      reject(new Error("Messages chat selection timed out."));
+    }, 20 * 60 * 1000);
+
+    server = createServer(async (req, res) => {
+      try {
+        const url = new URL(req.url ?? "/", `http://${req.headers.host ?? "127.0.0.1"}`);
+
+        if (req.method === "GET" && url.pathname === "/") {
+          sendHtml(res, renderMessagesSelectorPage(chats, token));
+          return;
+        }
+
+        if (req.method === "POST" && url.pathname === "/select") {
+          const body = await readRequestBody(req);
+          const form = new URLSearchParams(body);
+          if (form.get("token") !== token) {
+            sendHtml(res, renderMessagesDonePage("Invalid selection session.", true), 403);
+            return;
+          }
+          const selectedIds = form.getAll("chatId").filter(Boolean);
+          const selectedSet = new Set(selectedIds);
+          const selected = chats.filter((chat) => selectedSet.has(chat.chatId));
+          if (selected.length === 0) {
+            sendHtml(res, renderMessagesSelectorPage(chats, token, "Select at least one chat."));
+            return;
+          }
+
+          sendHtml(res, renderMessagesDonePage(`${selected.length} chat${selected.length === 1 ? "" : "s"} selected.`));
+          if (!settled) {
+            settled = true;
+            clearTimeout(timeout);
+            setTimeout(() => server.close(), 100);
+            resolve(selected);
+          }
+          return;
+        }
+
+        sendHtml(res, renderMessagesDonePage("Not found.", true), 404);
+      } catch (err) {
+        if (!settled) {
+          settled = true;
+          clearTimeout(timeout);
+          server?.close();
+          reject(err);
+        }
+      }
+    });
+
+    server.on("error", (err) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timeout);
+      reject(err);
+    });
+
+    server.listen(0, "127.0.0.1", async () => {
+      const address = server.address();
+      const port = typeof address === "object" && address ? address.port : null;
+      if (!port) {
+        settled = true;
+        clearTimeout(timeout);
+        server.close();
+        reject(new Error("Could not start local Messages selector."));
+        return;
+      }
+      const url = `http://127.0.0.1:${port}/`;
+      console.log(`\nOpening Messages chat selector: ${url}`);
+      await openOrPrint(url, { noOpen: Boolean(opts.noOpen) });
+      console.log("Select the Messages chats to sync in the browser.");
+    });
+  });
+}
+
+function renderMessagesSelectorPage(chats, token, error = "") {
+  const rows = chats.map((chat) => `
+      <label class="chat-row">
+        <input type="checkbox" name="chatId" value="${htmlAttr(chat.chatId)}">
+        <span class="box" aria-hidden="true"></span>
+        <span class="chat-main">
+          <span class="chat-top">
+            <span class="chat-name">${html(chat.label)}</span>
+            <span class="chat-kind">${html(chat.kind === "group" ? "Group" : chat.kind === "dm" ? "Contact" : "Chat")}</span>
+          </span>
+          ${renderChatPeople(chat)}
+          <span class="chat-meta">${html(formatMessageChatMeta(chat))}</span>
+        </span>
+      </label>`).join("");
+
+  return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Select Messages Chats</title>
+  <style>
+    :root {
+      color-scheme: light dark;
+      --bg: #FCFCFC;
+      --fg: #111111;
+      --muted: #6D726D;
+      --line: #E8ECE8;
+      --panel: #FFFFFF;
+      --button: #136033;
+      --button-text: #FFFFFF;
+      --link: #136033;
+      --radius: 10px;
+    }
+    @media (prefers-color-scheme: dark) {
+      :root {
+        --bg: #000000;
+        --fg: #F8F8F8;
+        --muted: #A2A8A2;
+        --line: #202520;
+        --panel: #070907;
+        --button: #FFFFFF;
+        --button-text: #000000;
+        --link: #136033;
+      }
+    }
+    * { box-sizing: border-box; }
+    body {
+      margin: 0;
+      background: var(--bg);
+      color: var(--fg);
+      font-family: Geist, "Geist Sans", ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+      letter-spacing: 0;
+    }
+    main {
+      width: min(760px, calc(100vw - 32px));
+      margin: 40px auto;
+    }
+    header {
+      display: flex;
+      justify-content: space-between;
+      gap: 16px;
+      align-items: end;
+      padding-bottom: 18px;
+      border-bottom: 1px solid var(--line);
+    }
+    h1 {
+      margin: 0;
+      font-size: 24px;
+      line-height: 1.1;
+      font-weight: 650;
+    }
+    .count {
+      color: var(--muted);
+      font-size: 13px;
+      white-space: nowrap;
+    }
+    form {
+      margin-top: 18px;
+    }
+    .error {
+      margin: 0 0 12px;
+      color: #9B1C1C;
+      font-size: 14px;
+    }
+    .chat-list {
+      display: grid;
+      gap: 8px;
+      margin: 0 0 18px;
+    }
+    .chat-row {
+      display: grid;
+      grid-template-columns: 24px 1fr;
+      gap: 12px;
+      align-items: start;
+      padding: 13px 14px;
+      background: var(--panel);
+      border: 1px solid var(--line);
+      border-radius: var(--radius);
+      cursor: pointer;
+    }
+    .chat-row:hover {
+      border-color: color-mix(in srgb, var(--link) 45%, var(--line));
+    }
+    input[type="checkbox"] {
+      position: absolute;
+      opacity: 0;
+      pointer-events: none;
+    }
+    .box {
+      width: 18px;
+      height: 18px;
+      margin-top: 2px;
+      border: 1.5px solid var(--muted);
+      border-radius: 5px;
+      display: inline-grid;
+      place-items: center;
+    }
+    input[type="checkbox"]:checked + .box {
+      background: var(--button);
+      border-color: var(--button);
+    }
+    input[type="checkbox"]:checked + .box::after {
+      content: "";
+      width: 7px;
+      height: 4px;
+      border-left: 2px solid var(--button-text);
+      border-bottom: 2px solid var(--button-text);
+      transform: rotate(-45deg) translateY(-1px);
+    }
+    .chat-main {
+      min-width: 0;
+      display: grid;
+      gap: 4px;
+    }
+    .chat-top {
+      display: flex;
+      gap: 10px;
+      align-items: center;
+      min-width: 0;
+    }
+    .chat-name {
+      overflow: hidden;
+      text-overflow: ellipsis;
+      white-space: nowrap;
+      font-size: 15px;
+      font-weight: 600;
+    }
+    .chat-kind {
+      color: var(--link);
+      font-size: 12px;
+      flex: none;
+    }
+    .chat-people,
+    .chat-meta {
+      color: var(--muted);
+      font-size: 13px;
+      line-height: 1.35;
+      overflow-wrap: anywhere;
+    }
+    .actions {
+      display: flex;
+      justify-content: flex-end;
+      position: sticky;
+      bottom: 0;
+      padding: 14px 0 0;
+      background: linear-gradient(to top, var(--bg) 70%, transparent);
+    }
+    button {
+      appearance: none;
+      border: 0;
+      border-radius: var(--radius);
+      background: var(--button);
+      color: var(--button-text);
+      padding: 10px 14px;
+      font: inherit;
+      font-weight: 620;
+      cursor: pointer;
+    }
+    a { color: var(--link); }
+  </style>
+</head>
+<body>
+  <main>
+    <header>
+      <h1>Select Messages chats</h1>
+      <div class="count">${chats.length} recent chats</div>
+    </header>
+    <form method="post" action="/select">
+      <input type="hidden" name="token" value="${htmlAttr(token)}">
+      ${error ? `<p class="error">${html(error)}</p>` : ""}
+      <div class="chat-list">${rows}</div>
+      <div class="actions">
+        <button type="submit">Use selected chats</button>
+      </div>
+    </form>
+  </main>
+</body>
+</html>`;
+}
+
+function renderMessagesDonePage(message, isError = false) {
+  return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Messages Selection</title>
+  <style>
+    :root { color-scheme: light dark; --bg: #FCFCFC; --fg: #111; --muted: #6D726D; --button: #136033; --button-text: #FFFFFF; --radius: 10px; }
+    @media (prefers-color-scheme: dark) { :root { --bg: #000; --fg: #F8F8F8; --muted: #A2A8A2; --button: #FFFFFF; --button-text: #000; } }
+    body { margin: 0; min-height: 100vh; display: grid; place-items: center; background: var(--bg); color: var(--fg); font-family: Geist, "Geist Sans", ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; letter-spacing: 0; }
+    main { width: min(420px, calc(100vw - 32px)); }
+    h1 { margin: 0 0 8px; font-size: 24px; line-height: 1.1; font-weight: 650; }
+    p { margin: 0; color: var(--muted); font-size: 14px; line-height: 1.45; }
+    .mark { width: 34px; height: 34px; border-radius: var(--radius); display: grid; place-items: center; margin-bottom: 14px; background: var(--button); color: var(--button-text); font-weight: 700; }
+  </style>
+</head>
+<body>
+  <main>
+    <div class="mark">${isError ? "!" : "OK"}</div>
+    <h1>${html(message)}</h1>
+    <p>${isError ? "Return to the terminal and retry." : "You can close this tab and return to the terminal."}</p>
+  </main>
+</body>
+</html>`;
+}
+
+function renderChatPeople(chat) {
+  const names = chat.participants?.map((participant) => participant.name ?? participant.handle).filter(Boolean) ?? [];
+  if (!names.length) return "";
+  return `<span class="chat-people">${html(names.slice(0, 6).join(", "))}</span>`;
+}
+
+function formatMessageChatMeta(chat) {
+  const parts = [];
+  if (chat.service) parts.push(chat.service);
+  if (chat.lastMessageAt) parts.push(new Date(chat.lastMessageAt).toLocaleString());
+  return parts.join(" · ");
+}
+
+function sendHtml(res, body, status = 200) {
+  res.writeHead(status, {
+    "Content-Type": "text/html; charset=utf-8",
+    "Cache-Control": "no-store",
+  });
+  res.end(body);
+}
+
+function readRequestBody(req) {
+  return new Promise((resolve, reject) => {
+    let body = "";
+    req.setEncoding("utf8");
+    req.on("data", (chunk) => {
+      body += chunk;
+      if (body.length > 64_000) {
+        reject(new Error("Request body too large."));
+        req.destroy();
+      }
+    });
+    req.on("end", () => resolve(body));
+    req.on("error", reject);
+  });
+}
+
 async function listRecentMessageChats({ limit }) {
   if (platform() !== "darwin") {
     throw new Error("local Messages chat discovery is only supported on macOS");
@@ -1675,6 +2042,17 @@ function parseAllowedChatIds(value) {
   return [...new Set(raw.map((chatId) => String(chatId).trim()).filter(Boolean))];
 }
 
+function html(value) {
+  return String(value ?? "")
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;");
+}
+
+function htmlAttr(value) {
+  return html(value).replace(/"/g, "&quot;");
+}
+
 class MessagesBatchSender {
   constructor(apiUrl, agentToken, userId) {
     this.apiUrl = trimTrailingSlash(apiUrl);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shepherd-onboard",
-  "version": "0.1.11",
+  "version": "0.1.12",
   "description": "Customer-facing Shepherd raw sync onboarding CLI",
   "type": "module",
   "bin": {