shepherd-onboard 0.1.20 → 0.1.21

package/bin/shepherd-onboard.js

@@ -17,6 +17,7 @@ const MAX_BATCH_SIZE = 50;
 const MAX_QUEUE_MESSAGES = 10_000;
 const DEFAULT_MESSAGE_CHAT_SEARCH_LIMIT = 200;
 const INITIAL_MESSAGE_CHAT_ROWS = 20;
+const AGENT_MODALITY_ORDER = ["google", "slack", "granola", "messages"];
 const SHEPHERD_LOGO_PATH = join(PACKAGE_DIR, "assets", "shepherd_G_vector_136033.png");
 const GRANOLA_API_KEYS_PATH = "/settings/integrations/api-keys";
 const GOOGLE_WORKSPACE_DELEGATION_ADMIN_URL = "https://admin.google.com/ac/owl/domainwidedelegation";
@@ -298,41 +299,23 @@ async function runAgentOnboarding() {
     createdAt: new Date().toISOString(),
   });
 
-  const opened = [];
-  let googleAdminConsole = null;
-  if (sources.google) {
-    googleAdminConsole = { url: GOOGLE_WORKSPACE_DELEGATION_ADMIN_URL };
-    if (!noOpen) {
-      await openGoogleWorkspaceDelegationAdmin({ noOpen: false });
-      googleAdminConsole.opened = true;
-    } else {
-      googleAdminConsole.opened = false;
-    }
-  }
-  for (const [provider, url] of Object.entries(session.authUrls ?? {})) {
-    if (typeof url !== "string") continue;
-    if (provider === "google") continue;
-    if (!noOpen) await openOrPrint(url, { noOpen: false });
-    opened.push(provider);
-  }
-
-  let granolaApiKeyPage = null;
-  if (sources.granola && !args["no-open-granola"]) {
-    granolaApiKeyPage = await openGranolaApiKeys({ noOpen });
-  }
+  const currentAction = await openNextAgentModality({
+    sources,
+    authUrls: session.authUrls ?? {},
+    noOpen,
+  });
 
   if (args.json) {
     console.log(JSON.stringify({
       status: "auth_required",
       account: publicAgentAccount(session.account),
-      opened,
+      opened: currentAction?.opened ? [currentAction.source] : [],
       googleWorkspaceDelegation: sources.google ? googleWorkspaceDelegationSetup(session.googleWorkspaceDelegation) : undefined,
-      googleAdminConsole,
-      granolaApiKeyPage,
+      currentAction,
       statePath,
       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),
+      needsUserAction: agentNeedsUserAction(sources, currentAction),
     }, null, 2));
     return;
   }
@@ -343,35 +326,13 @@ async function runAgentOnboarding() {
   if (session.account.organizationMatch?.type && session.account.organizationMatch.type !== "created") {
     console.log(`Matched existing organization by ${session.account.organizationMatch.type}.`);
   }
-  if (opened.length) {
-    console.log(`Opened browser authorization: ${opened.join(", ")}`);
-  }
-  if (sources.google) {
-    if (googleAdminConsole?.opened) {
-      console.log(`Opened Google Admin Console: ${googleAdminConsole.url}`);
-    }
-    console.log("\nGoogle Workspace domain-wide delegation setup:");
-    printGoogleWorkspaceDelegationSetup(session.googleWorkspaceDelegation);
-  }
-  if (noOpen) {
-    if (sources.google) console.log(`Google Admin Console domain-wide delegation URL: ${GOOGLE_WORKSPACE_DELEGATION_ADMIN_URL}`);
-    for (const [provider, url] of Object.entries(session.authUrls ?? {})) {
-      if (provider === "google") continue;
-      console.log(`${provider} auth URL: ${url}`);
-    }
-  }
   console.log(`State saved: ${statePath}`);
-  console.log("\nCoding agent next steps:");
-  let step = 1;
-  if (sources.google) {
-    console.log(`${step++}. Ask the user's Google Workspace super admin to authorize Shepherd in Google Admin Console with the Client ID and scopes above.`);
-  }
-  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, have the user select chats in the browser page, and keep the printed chat IDs.`);
-  }
-  console.log(`${step++}. Run:`);
+
+  printAgentCurrentAction(currentAction, {
+    googleWorkspaceDelegation: session.googleWorkspaceDelegation,
+  });
+
+  console.log("\nAfter that modality is complete, run:");
   console.log(`   ${agentCommand()} agent --continue --messages-handle "<phone_or_apple_id>" --messages-chat-ids "<comma_separated_chat_ids>" --granola-api-key "<granola_key>"`);
   console.log("   Omit either optional flag if that source is not being connected.");
 }
@@ -494,11 +455,20 @@ async function continueAgentOnboarding() {
   }
 
   const errors = finalized.errors && Object.keys(finalized.errors).length ? finalized.errors : null;
+  const currentAction = errors
+    ? await openNextAgentModality({
+        sources: state.sources,
+        authUrls: state.authUrls ?? {},
+        noOpen: Boolean(args["no-open"]),
+        pendingSources: pendingAgentSources(state.sources, errors),
+      })
+    : null;
   if (args.json) {
     console.log(JSON.stringify({
       status: errors ? "waiting" : "completed",
       connected: Object.keys(finalized.connected ?? {}),
       errors: errors ? safeErrorRecord(errors) : undefined,
+      currentAction,
       nextCommand: errors ? `${agentCommand()} agent --continue --messages-handle "<phone_or_apple_id>" --messages-chat-ids "<comma_separated_chat_ids>" --granola-api-key "<granola_key>"` : undefined,
     }, null, 2));
     return;
@@ -509,7 +479,12 @@ async function continueAgentOnboarding() {
     for (const [source, message] of Object.entries(errors)) {
       console.log(`- ${source}: ${safeError(message)}`);
     }
-    console.log("\nAfter the user completes missing auth/details, rerun:");
+
+    printAgentCurrentAction(currentAction, {
+      googleWorkspaceDelegation: state.googleWorkspaceDelegation,
+    });
+
+    console.log("\nAfter that modality is complete, rerun:");
     console.log(`   ${agentCommand()} agent --continue --messages-handle "<phone_or_apple_id>" --messages-chat-ids "<comma_separated_chat_ids>" --granola-api-key "<granola_key>"`);
     console.log("   Omit either optional flag if that source is not being connected.");
     return;
@@ -750,9 +725,9 @@ function printAgentContract() {
       "Selected local Messages chats from the browser selector, if they want local Messages connected",
     ],
     afterStartCommand: [
-      "For Google Workspace, have a super admin authorize the Shepherd Client ID and scopes in Google Admin Console.",
-      "Complete the opened Slack authorization.",
-      "Create/copy the Granola API key from the opened Granola Mac app API key screen, if they want Granola connected.",
+      "Handle only the current modality opened or printed by the command.",
+      "After the current modality is complete, run the continue command to advance to the next unresolved modality.",
+      "Do not open Slack, Granola, or Messages while Google Workspace is still waiting; do not open Granola or Messages while Slack is still waiting.",
     ],
     doNotDo: [
       "Do not run wiki generation.",
@@ -830,9 +805,9 @@ Add skip flags for sources the user did not select:
 - --no-granola
 - --no-messages
 
-That command creates/reuses the customer user and org, opens the Google Admin Console domain-wide delegation page if Google Workspace is selected, prints Google Workspace setup values, opens Slack browser auth if selected, and saves local state.
+That command creates/reuses the customer user and org, saves local state, and opens at most one source setup surface. It works one modality at a time after account setup: Google Workspace, then Slack, then Granola. If Messages details are still missing, it prints the Messages selector command instead of opening another auth surface. Do not manually open later source setup surfaces until the command tells you that source is the current modality.
 
-If Google Workspace is selected, the setup command opens the Admin Console domain-wide delegation page. Show this setup to the user and have their Google Workspace super admin authorize it:
+If Google Workspace is the current modality, the setup command opens the Admin Console domain-wide delegation page. Show this setup to the user and have their Google Workspace super admin authorize it:
 
 App name: ${payload.googleWorkspaceDelegation.appName}
 Service account email: ${payload.googleWorkspaceDelegation.serviceAccountEmail}
@@ -846,17 +821,17 @@ The setup command copies those scopes to the clipboard as one comma-separated st
 The customer does not create a service account and does not upload service account JSON in the default Shepherd-managed flow. Their super admin only authorizes the Client ID and scopes in Google Admin Console. Shepherd's backend stores and uses its private service account JSON server-side.
 Shepherd must still enforce selected users and groups internally before polling or impersonating any employee email.
 
-If Slack is selected and your browser automation can complete that auth screen, do it. If it cannot click through OAuth screens, leave the opened browser tab for the user and ask them to complete Slack auth.
+If Slack is the current modality and your browser automation can complete that auth screen, do it. If it cannot click through OAuth screens, leave the opened browser tab for the user and ask them to complete Slack auth. Do not open Granola or Messages until Slack is complete and the continue command advances.
 
-If Granola is selected, it also opens the Granola desktop app. If your local app automation can navigate it, go to:
+If Granola is the current modality, the command opens the Granola desktop app. If your local app automation can navigate it, go to:
   Settings -> Connectors -> API keys
 Then have the user create/copy the API key.
 
-If Granola did not come forward, run:
+If Granola is the current modality and did not come forward, run:
   ${payload.granolaApiKeyCommand}
 That command opens Granola and tries to navigate to Settings -> Connectors -> API keys. If your tool cannot click inside Granola, leave Granola open and ask the user to go to that screen.
 
-After Google Workspace Admin Console delegation and Slack browser auth are complete, and after the user has copied a Granola API key from the opened Granola screen if they want Granola, run:
+After the current modality is complete, run:
   ${payload.continueCommand} --messages-handle "<phone_or_apple_id>" --messages-chat-ids "<comma_separated_chat_ids>" --granola-api-key "<granola_key>"
 
 Omit either optional flag if that source is not being connected.
@@ -973,13 +948,108 @@ function authenticatedName(authenticated) {
   return authenticated?.workosUser?.name ?? authenticated?.account?.name ?? null;
 }
 
-function agentNeedsUserAction(sources, opened) {
-  const actions = [];
-  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, have the user select local Messages contacts/groups in the browser, then pass the printed chat IDs with the Messages handle.");
-  return actions;
+function pendingAgentSources(sources, errors) {
+  const pending = new Set(Object.keys(errors ?? {}));
+  return AGENT_MODALITY_ORDER.filter((source) => sources?.[source] && pending.has(source));
+}
+
+async function openNextAgentModality({ sources, authUrls = {}, noOpen = false, pendingSources = null }) {
+  const pending = pendingSources ?? AGENT_MODALITY_ORDER.filter((source) => sources?.[source]);
+  for (const source of AGENT_MODALITY_ORDER) {
+    if (!sources?.[source] || !pending.includes(source)) continue;
+
+    if (source === "google") {
+      return {
+        source,
+        label: "Google Workspace",
+        ...await openGoogleWorkspaceDelegationAdmin({ noOpen }),
+      };
+    }
+
+    if (source === "slack") {
+      const url = typeof authUrls.slack === "string" ? authUrls.slack : null;
+      if (!url) {
+        return {
+          source,
+          label: "Slack",
+          opened: false,
+          message: "Slack authorization URL was not returned by Shepherd.",
+        };
+      }
+      await openOrPrint(url, { noOpen });
+      return { source, label: "Slack", opened: !noOpen, url };
+    }
+
+    if (source === "granola") {
+      const result = await openGranolaApiKeys({ noOpen: noOpen || Boolean(args["no-open-granola"]) });
+      return { source, label: "Granola", ...result };
+    }
+
+    if (source === "messages") {
+      return {
+        source,
+        label: "Messages",
+        opened: false,
+        command: `${agentCommand()} messages-chats`,
+        message: "Run the local Messages chat selector and keep the printed chat IDs.",
+      };
+    }
+  }
+
+  return null;
+}
+
+function printAgentCurrentAction(action, opts = {}) {
+  if (!action) {
+    console.log("\nNo source setup page was opened.");
+    return;
+  }
+
+  console.log(`\nCurrent modality: ${action.label}`);
+
+  if (action.source === "google") {
+    if (action.opened) {
+      console.log(`Opened Google Admin Console: ${action.url}`);
+    } else {
+      console.log(`Google Admin Console domain-wide delegation URL: ${action.url}`);
+    }
+    console.log("\nGoogle Workspace domain-wide delegation setup:");
+    printGoogleWorkspaceDelegationSetup(opts.googleWorkspaceDelegation);
+    console.log("\nAsk the user's Google Workspace super admin to authorize Shepherd before opening another source.");
+    return;
+  }
+
+  if (action.source === "slack") {
+    if (action.opened) {
+      console.log("Opened Slack authorization in the browser.");
+    } else if (action.url) {
+      console.log(`Slack authorization URL: ${action.url}`);
+    } else if (action.message) {
+      console.log(action.message);
+    }
+    console.log("Ask the user to complete Slack authorization before opening another source.");
+    return;
+  }
+
+  if (action.source === "granola") {
+    if (action.target) console.log(`Granola target: ${action.target}`);
+    console.log("Ask the user to create/copy the Granola API key before opening another source.");
+    return;
+  }
+
+  if (action.source === "messages") {
+    console.log(`Run: ${action.command}`);
+    console.log("Have the user select specific local Messages chats; do not select all by default.");
+  }
+}
+
+function agentNeedsUserAction(sources, action) {
+  if (!action) return [];
+  if (action.source === "google") return ["Have the customer's Google Workspace super admin authorize Shepherd's domain-wide delegation Client ID and scopes in Google Admin Console."];
+  if (action.source === "slack") return ["Complete Slack browser authorization."];
+  if (action.source === "granola") return ["Create/copy a Granola API key from the Granola Mac app."];
+  if (action.source === "messages") return ["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 [];
 }
 
 function agentCommand() {

package/package.json

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