shepherd-onboard 0.1.5 → 0.1.7

package/README.md

@@ -25,9 +25,9 @@ The command:
 - asks for name, organization, and an optional local Messages handle
 - creates or reuses the Shepherd customer account from the WorkOS-authenticated email
 - creates or reuses the organization, including case-insensitive and close-name matches
-- opens Google authorization for Gmail, Docs, and Calendar consent
+- opens Google Workspace authorization for Gmail, Drive, Docs, and Calendar consent
 - opens Slack authorization
-- opens Granola's API key screen with `open 'granola://settings/connectors/api-keys'`
+- opens the Granola desktop app to Settings -> Connectors -> API keys
 - collects the Granola API key after opening the Granola screen when Granola is enabled
 - sets up local macOS Messages raw sync with a background LaunchAgent
 - starts raw polling/backfill for connected sources
@@ -44,10 +44,18 @@ The command does not expose Railway, database, Redis, or internal service detail
 --granola-api-key <key>    Granola API key
 --messages-handle <value>  Messages phone number or Apple ID email
 --messages-backfill-days   Local Messages backfill window, default 30
---no-google                Skip Google/Gmail/Docs/Calendar
+--no-google                Skip Google Workspace (Gmail/Drive/Docs/Calendar)
 --no-slack                 Skip Slack
 --no-granola               Skip Granola
 --no-open-granola          Do not open the Granola API key screen
 --no-messages              Skip local Messages
 --no-open                  Print auth URLs instead of opening the browser
 ```
+
+## Granola API Keys
+
+If Granola does not land on the API keys page, run:
+
+```sh
+npx -y shepherd-onboard@latest granola-api-keys
+```

package/bin/shepherd-onboard.js

@@ -32,6 +32,8 @@ async function dispatch() {
     await runOnboarding();
   } else if (command === "agent") {
     await runAgentOnboarding();
+  } else if (command === "granola-api-keys") {
+    await openGranolaApiKeys({ noOpen: Boolean(args["no-open"]) });
   } else if (command === "messages-agent") {
     await runMessagesAgent();
   } else {
@@ -80,9 +82,9 @@ async function runOnboarding() {
   }
 
   if (session.authUrls?.google) {
-    console.log("\nGoogle, Gmail, Docs, and Calendar authorization");
+    console.log("\nGoogle Workspace authorization");
     await openOrPrint(session.authUrls.google, { noOpen });
-    await waitForEnter("Complete Google authorization in the browser, then press Enter.");
+    await waitForEnter("Complete Google Workspace authorization in the browser, then press Enter.");
   }
 
   if (session.authUrls?.slack) {
@@ -489,6 +491,7 @@ Usage:
   npx -y ${PACKAGE_NAME}@latest agent --name <name> --org <organization>
   npx -y ${PACKAGE_NAME}@latest agent --continue --granola-api-key <key> --messages-handle <value>
   npx -y ${PACKAGE_NAME}@latest agent --status
+  npx -y ${PACKAGE_NAME}@latest granola-api-keys
 
 Agent mode is non-interactive. It prints the user prompt and exact commands a coding agent should run.
 Always run --login first. WorkOS login/signup creates or relinks the Shepherd account before source setup.
@@ -516,6 +519,7 @@ Options:
 Usage:
   npx -y ${PACKAGE_NAME}@latest
   npx -y ${PACKAGE_NAME}@latest agent
+  npx -y ${PACKAGE_NAME}@latest granola-api-keys
 
 Options:
   --email <email>            Advanced: must match the WorkOS-authenticated email.
@@ -525,7 +529,7 @@ Options:
   --messages-handle <value>  Messages phone number or Apple ID email.
   --messages-backfill-days <days>
                              Local Messages backfill window. Defaults to 30.
-  --no-google                Skip Google/Gmail/Docs/Calendar.
+  --no-google                Skip Google Workspace (Gmail/Drive/Docs/Calendar).
   --no-slack                 Skip Slack.
   --no-granola               Skip Granola.
   --no-open-granola          Do not open the Granola API key screen.
@@ -561,7 +565,7 @@ function printAgentContract() {
       {
         label: "Sources",
         prompt: "Which sources should Shepherd connect for raw sync?",
-        options: ["Google/Gmail/Docs/Calendar", "Slack", "Granola", "Messages"],
+        options: ["Google Workspace (Gmail/Drive/Docs/Calendar)", "Slack", "Granola", "Messages"],
         multiSelect: true,
       },
       {
@@ -576,7 +580,7 @@ function printAgentContract() {
       "Messages phone number or Apple ID email, if they want local Messages connected",
     ],
     afterStartCommand: [
-      "Complete the opened Google authorization for Gmail, Docs, and Calendar.",
+      "Complete the opened Google Workspace authorization for Gmail, Drive, Docs, and Calendar.",
       "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.",
     ],
@@ -597,7 +601,8 @@ function printAgentContract() {
     ],
     statusCommand: `${command} agent --status`,
     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.",
-    granolaApiKeyCommand: "open 'granola://settings/connectors/api-keys'",
+    granolaApiKeyCommand: `${command} granola-api-keys`,
+    granolaApiKeyPath: "Granola desktop app -> Settings -> Connectors -> API keys",
   };
 
   if (args.json) {
@@ -615,7 +620,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/Gmail/Docs/Calendar, Slack, Granola, Messages. Allow multi-select if your interface supports it.
+2. Sources: Google Workspace (Gmail/Drive/Docs/Calendar), Slack, Granola, Messages. Allow multi-select if your interface supports it.
 3. Messages, if selected: Skip Messages, or Provide handle.
 
 Before source setup, always run:
@@ -641,12 +646,18 @@ 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/Slack browser auth, and saves local state.
-It also runs:
-  open 'granola://settings/connectors/api-keys'
-and activates Granola so the user can create/copy the API key.
+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.
 
-After Google/Gmail/Docs/Calendar 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:
+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
+Then have the user create/copy the API key.
+
+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:
   ${payload.continueCommand} --messages-handle "<phone_or_apple_id>" --granola-api-key "<granola_key>"
 
 Omit either optional flag if that source is not being connected.
@@ -723,7 +734,7 @@ function authenticatedName(authenticated) {
 
 function agentNeedsUserAction(sources, opened) {
   const actions = [];
-  if (sources.google && opened.includes("google")) actions.push("Complete Google browser authorization for Gmail, Docs, and Calendar consent.");
+  if (sources.google && opened.includes("google")) actions.push("Complete Google Workspace browser authorization for Gmail, Drive, Docs, and Calendar consent.");
   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("Pass the Messages phone number or Apple ID email collected before starting onboarding.");
@@ -838,10 +849,10 @@ async function openOrPrint(url, opts) {
 }
 
 async function openGranolaApiKeys(opts = {}) {
-  const deepLink = "granola://settings/connectors/api-keys";
+  const deepLink = "granola://settings/integrations";
   if (opts.noOpen) {
-    console.log(`Granola API keys: ${deepLink}`);
-    return { opened: false, target: deepLink };
+    console.log("Granola API keys: open the Granola desktop app -> Settings -> Connectors -> API keys");
+    return { opened: false, target: "Granola Settings -> Connectors -> API keys" };
   }
 
   if (platform() !== "darwin") {
@@ -850,24 +861,57 @@ async function openGranolaApiKeys(opts = {}) {
   }
 
   console.log("\nOpening Granola API keys");
-  const deepLinkResult = await execFileQuiet("open", [deepLink], { ignoreError: true, captureError: true });
-  await sleep(700);
-  const activateResult = await execFileQuiet("osascript", [
+  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);
+  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 (deepLinkResult.error || activateResult.error) {
+  if (bundleResult.error && activateByBundleResult.error && activateByNameResult.error) {
     await execFileQuiet("open", ["-a", "Granola"], { ignoreError: true });
   }
+  await navigateGranolaApiKeysWithAppleScript();
 
   return {
     opened: true,
-    target: deepLink,
-    fallback: "If Granola does not land on the API key screen, open Settings -> Connectors -> API keys in Granola.",
+    target: "Granola Settings -> Connectors -> API keys",
+    attemptedDeepLink: deepLink,
+    fallback: "If local app automation cannot click inside Granola, ask the user to open Settings -> Connectors -> API keys.",
   };
 }
 
+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 + 665}
+      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 + 665}
+      return
+    end try
+  end tell
+end tell
+`;
+  await execFileQuiet("osascript", ["-e", script], { ignoreError: true });
+}
+
 async function postJson(url, body, opts = {}) {
   const res = await fetch(url, {
     method: "POST",

package/package.json

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