shepherd-onboard 0.1.10 → 0.1.11

package/README.md

@@ -10,7 +10,7 @@ Give this to a coding agent:
 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, open source auth, open Granola's API key page, finalize, start cloud raw polling/backfills, and install local Messages sync.
+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.
 Existing-organization joins are verified from Shepherd login and company email domain; the typed org name is not trusted by itself.
 
@@ -27,7 +27,7 @@ The command:
 - creates or reuses the Shepherd customer account from the WorkOS-authenticated email
 - creates or reuses the organization, including case-insensitive and close-name matches
 - only reuses an existing organization when the authenticated account is allowed to join it
-- opens Google Workspace authorization for Gmail, Drive, Docs, and Calendar consent
+- prints Google Workspace domain-wide delegation setup for a Workspace super admin
 - 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
@@ -38,6 +38,22 @@ The command:
 
 The command does not expose Railway, database, Redis, or internal service details to the user.
 
+## Google Workspace Domain-wide Delegation
+
+Business customers connect Google Workspace once as an admin. Employees do not create service accounts and do not each complete Google OAuth for Gmail, Calendar, Drive, Docs, Sheets, Slides, Tasks, or Contacts.
+
+Customer-side setup in Google Admin Console:
+
+```text
+App name: Shepherd
+Service account email: gigabrain-delegation@shepherd-gigabrain.iam.gserviceaccount.com
+Domain-wide delegation OAuth Client ID: 118363960386741325727
+```
+
+The customer super admin authorizes that Client ID with the scopes printed by the CLI. The customer does not upload service account JSON; Shepherd stores its private service account JSON server-side in `GOOGLE_WORKSPACE_SERVICE_ACCOUNT_KEY_JSON` and requests delegated tokens with `sub=<allowed_employee_email>`.
+
+Shepherd must still enforce selected users and groups internally before impersonating or polling employee emails.
+
 ## Options
 
 ```sh
@@ -48,7 +64,7 @@ The command does not expose Railway, database, Redis, or internal service detail
 --messages-handle <value>  Messages phone number or Apple ID email
 --messages-chat-ids <ids>  Comma-separated chat IDs selected from messages-chats
 --messages-backfill-days   Local Messages backfill window, default 30
---no-google                Skip Google Workspace (Gmail/Drive/Docs/Calendar)
+--no-google                Skip Google Workspace (Gmail/Drive/Docs/Calendar/Sheets/Slides/Tasks/Contacts)
 --no-slack                 Skip Slack
 --no-granola               Skip Granola
 --no-open-granola          Do not open the Granola API key screen

package/bin/shepherd-onboard.js

@@ -13,6 +13,7 @@ const DEFAULT_AGENT_STATE_PATH = join(homedir(), ".shepherd", "raw-onboarding-ag
 const MAX_BATCH_SIZE = 50;
 const MAX_QUEUE_MESSAGES = 10_000;
 const DEFAULT_RECENT_MESSAGE_CHATS = 20;
+const GRANOLA_API_KEYS_PATH = "/settings/integrations/api-keys";
 const GOOGLE_WORKSPACE_DELEGATION_APP_NAME = "Shepherd";
 const GOOGLE_WORKSPACE_DELEGATION_SERVICE_ACCOUNT_EMAIL =
   "gigabrain-delegation@shepherd-gigabrain.iam.gserviceaccount.com";
@@ -283,7 +284,9 @@ async function runAgentOnboarding() {
     account: session.account,
     sources,
     authUrls: session.authUrls ?? {},
-    googleWorkspaceDelegation: googleWorkspaceDelegationSetup(session.googleWorkspaceDelegation),
+    googleWorkspaceDelegation: sources.google
+      ? googleWorkspaceDelegationSetup(session.googleWorkspaceDelegation)
+      : undefined,
     workosAuth,
     createdAt: new Date().toISOString(),
   });
@@ -337,15 +340,16 @@ async function runAgentOnboarding() {
   }
   console.log(`State saved: ${statePath}`);
   console.log("\nCoding agent next steps:");
+  let step = 1;
   if (sources.google) {
-    console.log("1. Ask the user's Google Workspace super admin to authorize Shepherd in Google Admin Console with the Client ID and scopes above.");
+    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("2. Ask the user to finish the opened Slack browser authorization.");
-  if (sources.granola) console.log("3. Ask the user for their Granola API key from the Granola Mac app.");
+  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(`4. 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 --json, ask the user which recent chats to sync, and keep those chat IDs.`);
   }
-  console.log("5. Run:");
+  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>"`);
   console.log("   Omit either optional flag if that source is not being connected.");
 }
@@ -758,7 +762,7 @@ Ask with short interactive prompts, not as one pasted checklist.
 
 Start with selection questions to determine intent:
 1. Organization: Join existing org, or Create new org.
-2. Sources: Google Workspace (Gmail/Drive/Docs/Calendar), Slack, Granola, Messages. Allow multi-select if your interface supports it.
+2. Sources: Google Workspace (Gmail/Drive/Docs/Calendar/Sheets/Slides/Tasks/Contacts), Slack, Granola, Messages. Allow multi-select if your interface supports it.
 3. Messages, if selected: Skip Messages, or Provide handle.
 
 When discussing existing orgs, keep it short: Shepherd verifies the join from their Shepherd login and company email domain. The org name they type is not trusted by itself.
@@ -767,6 +771,7 @@ Before source setup, always run:
   ${payload.loginCommand}
 
 That opens one WorkOS Shepherd login/signup flow and saves a local onboarding auth session. It creates or relinks the Shepherd customer account; the next setup command attaches sources to the same production cloud account rows.
+Do not use WorkOS Auth, WorkOS Pipes, or per-user Google OAuth for Google Workspace. WorkOS login is only Shepherd account identity.
 
 Ask the user for:
 1. Full name
@@ -791,8 +796,21 @@ Add skip flags for sources the user did not select:
 - --no-granola
 - --no-messages
 
-That command creates/reuses the customer user and org, opens Google Workspace/Slack browser auth, and saves local state.
-If your browser automation can complete those auth screens, do it. If it cannot click through OAuth screens, leave the opened browser tabs for the user and ask them to complete Google Workspace and Slack auth.
+That command creates/reuses the customer user and org, prints Google Workspace domain-wide delegation setup values, opens Slack browser auth if selected, and saves local state.
+
+If Google Workspace is selected, show this Admin Console setup to the user and have their Google Workspace super admin authorize it:
+
+App name: ${payload.googleWorkspaceDelegation.appName}
+Service account email: ${payload.googleWorkspaceDelegation.serviceAccountEmail}
+Domain-wide delegation OAuth Client ID: ${payload.googleWorkspaceDelegation.clientId}
+
+Scopes:
+${payload.googleWorkspaceDelegation.scopes.join("\n")}
+
+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 Granola is selected, it also opens the Granola desktop app. If your local app automation can navigate it, go to:
   Settings -> Connectors -> API keys
@@ -802,7 +820,7 @@ If Granola 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 and Slack browser auth is complete, and after the user has copied a Granola API key from the opened Granola screen if they want Granola, run:
+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:
   ${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.
@@ -1017,7 +1035,7 @@ async function openOrPrint(url, opts) {
 }
 
 async function openGranolaApiKeys(opts = {}) {
-  const deepLink = "granola://settings/integrations";
+  const deepLink = granolaApiKeysDeepLink();
   if (opts.noOpen) {
     console.log("Granola API keys: open the Granola desktop app -> Settings -> Connectors -> API keys");
     return { opened: false, target: "Granola Settings -> Connectors -> API keys" };
@@ -1030,19 +1048,20 @@ async function openGranolaApiKeys(opts = {}) {
 
   console.log("\nOpening Granola API keys");
   const bundleResult = await execFileQuiet("open", ["-b", "com.granola.app"], { ignoreError: true, captureError: true });
-  await sleep(500);
-  await execFileQuiet("open", [deepLink], { ignoreError: true, captureError: true });
-  await sleep(500);
+  await sleep(900);
+  const deepLinkResult = await execFileQuiet("open", ["-u", deepLink], { ignoreError: true, captureError: true });
+  await sleep(700);
+  const deepLinkRetryResult = await execFileQuiet("open", ["-u", deepLink], { ignoreError: true, captureError: true });
+  await sleep(300);
   const activateByBundleResult = await execFileQuiet("osascript", [
     "-e",
     'tell application id "com.granola.app" to activate',
   ], { ignoreError: true, captureError: true });
   const activateByNameResult = await execFileQuiet("open", ["-a", "Granola"], { ignoreError: true, captureError: true });
 
-  if (bundleResult.error && activateByBundleResult.error && activateByNameResult.error) {
+  if (bundleResult.error && deepLinkResult.error && deepLinkRetryResult.error && activateByBundleResult.error && activateByNameResult.error) {
     await execFileQuiet("open", ["-a", "Granola"], { ignoreError: true });
   }
-  await navigateGranolaApiKeysWithAppleScript();
 
   return {
     opened: true,
@@ -1052,32 +1071,8 @@ async function openGranolaApiKeys(opts = {}) {
   };
 }
 
-async function navigateGranolaApiKeysWithAppleScript() {
-  const script = `
-tell application id "com.granola.app" to activate
-delay 0.7
-tell application "System Events"
-  if not (exists process "Granola") then return
-  tell process "Granola"
-    set frontmost to true
-    try
-      set {x, y} to position of window 1
-      set {w, h} to size of window 1
-      click at {x + w - 55, y + 810}
-      return
-    end try
-    try
-      keystroke "," using command down
-      delay 0.5
-      set {x, y} to position of window 1
-      set {w, h} to size of window 1
-      click at {x + w - 55, y + 810}
-      return
-    end try
-  end tell
-end tell
-`;
-  await execFileQuiet("osascript", ["-e", script], { ignoreError: true });
+function granolaApiKeysDeepLink() {
+  return `granola://open?path=${encodeURIComponent(GRANOLA_API_KEYS_PATH)}`;
 }
 
 async function postJson(url, body, opts = {}) {

package/package.json

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