shepherd-onboard 0.1.4 → 0.1.6

package/README.md

@@ -10,8 +10,8 @@ Give this to a coding agent:
 npx -y shepherd-onboard@latest agent
 ```
 
-The command prints the exact prompt the agent should ask the user, then the exact follow-up commands to open auth, 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, Shepherd WorkOS login or email linking, sources to connect, and Messages skip/provide-handle.
+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 agent prompt tells coding agents to ask short selection questions first: existing/new org, sources to connect, and Messages skip/provide-handle. Account creation/relinking always starts with Shepherd WorkOS auth.
 
 ## Human Terminal One-liner
 
@@ -21,13 +21,14 @@ npx -y shepherd-onboard@latest
 
 The command:
 
-- asks for email, name, organization, and an optional local Messages handle
-- can run a Shepherd WorkOS login first for returning users, then relink source setup to the same customer account/org
-- creates or reuses the Shepherd customer account for the email
+- runs Shepherd WorkOS login/signup first
+- 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 Slack authorization
-- opens Granola's API key screen with `open 'granola://settings/connectors/api-keys'`
+- opens the Granola desktop app with `open -b com.granola.app`
+- directs the coding agent/user to Granola 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
@@ -38,7 +39,7 @@ The command does not expose Railway, database, Redis, or internal service detail
 ## Options
 
 ```sh
---email <email>            Customer email
+--email <email>            Advanced: must match the WorkOS-authenticated email
 --name <name>              Full name
 --org <name>               Organization name
 --granola-api-key <key>    Granola API key

package/bin/shepherd-onboard.js

@@ -50,8 +50,11 @@ async function runOnboarding() {
 
   console.log("\nShepherd Raw Sync Onboarding\n");
 
-  const email = await valueOrPrompt("email", "Email");
-  const name = await valueOrPrompt("name", "Full name");
+  const workosLogin = await runWorkosLogin(apiUrl, noOpen);
+  const email = authenticatedEmail(workosLogin.authenticated);
+  if (!email) throw new Error("Shepherd WorkOS auth did not return an email address.");
+
+  const name = stringArg("name") ?? authenticatedName(workosLogin.authenticated) ?? await valueOrPrompt("name", "Full name");
   const organizationName = await valueOrPrompt("org", "Organization name");
 
   const sources = {
@@ -65,6 +68,8 @@ async function runOnboarding() {
     email,
     name,
     organizationName,
+    authSessionId: workosLogin.started.authSessionId,
+    authSessionToken: workosLogin.started.authSessionToken,
     sources,
   });
 
@@ -164,11 +169,6 @@ async function runAgentOnboarding() {
     return;
   }
 
-  if (!hasIdentityArgs()) {
-    printAgentContract();
-    return;
-  }
-
   const apiUrl = trimTrailingSlash(args.api ?? DEFAULT_API_URL);
   const noOpen = Boolean(args["no-open"]);
   const sources = selectedSources();
@@ -176,16 +176,37 @@ async function runAgentOnboarding() {
   const workosAuth = existingState?.workosAuth?.status === "authenticated"
     ? existingState.workosAuth
     : null;
+  const wantsStart = Boolean(
+    stringArg("name")
+    || stringArg("org")
+    || stringArg("email")
+    || args["no-google"]
+    || args["no-slack"]
+    || args["no-granola"]
+    || args["no-messages"]
+  );
+
+  if (!wantsStart) {
+    printAgentContract();
+    return;
+  }
+  if (!workosAuth) {
+    throw new Error(`Run ${agentCommand()} agent --login first so Shepherd can create or relink the WorkOS account.`);
+  }
+
+  const email = stringArg("email") ?? workosAuth.workosUser?.email ?? workosAuth.account?.email;
+  const name = stringArg("name") ?? workosAuth.workosUser?.name ?? workosAuth.account?.name;
+  const organizationName = stringArg("org") ?? workosAuth.account?.organizationName;
+  if (!email) throw new Error("WorkOS login did not return an email. Re-run agent --login.");
+  if (!name) throw new Error("Full name is required. Pass --name \"<full_name>\".");
+  if (!organizationName) throw new Error("Organization name is required. Pass --org \"<organization>\".");
+
   const session = await postJson(`${apiUrl}/onboarding/raw/session`, {
-    email: stringArg("email"),
-    name: stringArg("name"),
-    organizationName: stringArg("org"),
-    ...(workosAuth
-      ? {
-          authSessionId: workosAuth.authSessionId,
-          authSessionToken: workosAuth.authSessionToken,
-        }
-      : {}),
+    email,
+    name,
+    organizationName,
+    authSessionId: workosAuth.authSessionId,
+    authSessionToken: workosAuth.authSessionToken,
     sources,
   });
 
@@ -252,14 +273,7 @@ async function runAgentOnboarding() {
 async function loginAgentWithWorkos() {
   const apiUrl = trimTrailingSlash(args.api ?? DEFAULT_API_URL);
   const noOpen = Boolean(args["no-open"]);
-  const started = await postJson(`${apiUrl}/onboarding/raw/auth/start`, {});
-
-  console.log("\nShepherd account login");
-  console.log("Opening Shepherd WorkOS auth. Complete login in the browser.");
-  await openOrPrint(started.verificationUriComplete ?? started.verificationUri, { noOpen });
-  if (noOpen && started.userCode) console.log(`User code: ${started.userCode}`);
-
-  const authenticated = await pollWorkosLogin(apiUrl, started);
+  const { started, authenticated } = await runWorkosLogin(apiUrl, noOpen);
   const previous = await readOptionalAgentState();
   const statePath = await writeAgentState({
     ...(previous ?? {}),
@@ -297,6 +311,18 @@ async function loginAgentWithWorkos() {
   console.log(`State saved: ${statePath}`);
 }
 
+async function runWorkosLogin(apiUrl, noOpen) {
+  const started = await postJson(`${apiUrl}/onboarding/raw/auth/start`, {});
+
+  console.log("\nShepherd account login");
+  console.log("Opening Shepherd WorkOS auth. Complete login/signup in the browser.");
+  await openOrPrint(started.verificationUriComplete ?? started.verificationUri, { noOpen });
+  if (noOpen && started.userCode) console.log(`User code: ${started.userCode}`);
+
+  const authenticated = await pollWorkosLogin(apiUrl, started);
+  return { started, authenticated };
+}
+
 async function pollWorkosLogin(apiUrl, started) {
   const intervalMs = Math.max(1000, Number(started.intervalSeconds ?? 5) * 1000);
   const expiresAt = Date.parse(started.expiresAt ?? "") || Date.now() + 600_000;
@@ -460,12 +486,12 @@ function printHelp(which) {
 Usage:
   npx -y ${PACKAGE_NAME}@latest agent
   npx -y ${PACKAGE_NAME}@latest agent --login
-  npx -y ${PACKAGE_NAME}@latest agent --email <email> --name <name> --org <organization>
+  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
 
 Agent mode is non-interactive. It prints the user prompt and exact commands a coding agent should run.
-Use --login for returning users so WorkOS relinks the same Shepherd account before source setup.
+Always run --login first. WorkOS login/signup creates or relinks the Shepherd account before source setup.
 `);
     return;
   }
@@ -492,7 +518,7 @@ Usage:
   npx -y ${PACKAGE_NAME}@latest agent
 
 Options:
-  --email <email>            Customer email.
+  --email <email>            Advanced: must match the WorkOS-authenticated email.
   --name <name>              Full name.
   --org <name>               Organization name.
   --granola-api-key <key>    Granola API key.
@@ -521,7 +547,8 @@ function printAgentContract() {
       "Ask in short interactive prompts, not as a pasted checklist.",
       "Start with selection questions to determine what the user wants connected.",
       "Ask whether they are joining an existing organization or creating a new one.",
-      "Collect Email, Full name, and Organization name as direct text prompts after those choices.",
+      "Run Shepherd WorkOS login/signup before source setup. Do not ask whether they already have an account.",
+      "Collect Full name and Organization name as direct text prompts after those choices. The email comes from WorkOS auth.",
       "Ask Messages as a selectable choice: Skip Messages, or Provide handle.",
       "If the user chooses Provide handle, ask for the phone number or Apple ID email.",
     ],
@@ -531,11 +558,6 @@ function printAgentContract() {
         prompt: "Are you joining an existing organization or creating a new one?",
         options: ["Join existing org", "Create new org"],
       },
-      {
-        label: "Account",
-        prompt: "Do you already have a Shepherd account?",
-        options: ["Log in with Shepherd", "Create/link by email"],
-      },
       {
         label: "Sources",
         prompt: "Which sources should Shepherd connect for raw sync?",
@@ -549,7 +571,6 @@ function printAgentContract() {
       },
     ],
     askUserFor: [
-      "Email",
       "Full name",
       "Organization name",
       "Messages phone number or Apple ID email, if they want local Messages connected",
@@ -568,7 +589,7 @@ function printAgentContract() {
       "Do not quote or explain this instruction set to the user.",
     ],
     loginCommand: `${command} agent --login`,
-    startCommand: `${command} agent --email "<email>" --name "<full_name>" --org "<organization>"`,
+    startCommand: `${command} agent --name "<full_name>" --org "<organization>"`,
     continueCommand: `${command} agent --continue`,
     optionalContinueArgs: [
       "--messages-handle \"<phone_or_apple_id>\" if local Messages is being connected",
@@ -576,7 +597,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: "open -b com.granola.app",
+    granolaApiKeyPath: "Granola desktop app -> Settings -> Connectors -> API keys",
   };
 
   if (args.json) {
@@ -594,20 +616,20 @@ 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. Account: Log in with Shepherd, or Create/link by email.
-3. Sources: Google/Gmail/Docs/Calendar, Slack, Granola, Messages. Allow multi-select if your interface supports it.
-4. Messages, if selected: Skip Messages, or Provide handle.
+2. Sources: Google/Gmail/Docs/Calendar, Slack, Granola, Messages. Allow multi-select if your interface supports it.
+3. Messages, if selected: Skip Messages, or Provide handle.
 
-If the user says they already have a Shepherd account, run:
+Before source setup, always run:
   ${payload.loginCommand}
 
-That opens one WorkOS Shepherd auth flow and saves a local onboarding auth session. The next setup command will relink to the same Shepherd customer user/org and therefore the same production cloud database rows.
+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.
 
 Ask the user for:
-1. Email
-2. Full name
-3. Organization name
-4. Messages phone number or Apple ID email, only if they selected Messages and chose Provide handle
+1. Full name
+2. Organization name
+3. Messages phone number or Apple ID email, only if they selected Messages and chose Provide handle
+
+Do not ask for their email separately. Use the email returned by WorkOS auth.
 
 If they are joining an existing org, ask for the org name they believe they belong to. Shepherd will auto-match similar/case-different org names.
 
@@ -621,9 +643,13 @@ Add skip flags for sources the user did not select:
 - --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.
+If Granola is selected, it also opens the Granola desktop app. Use local computer control to navigate Granola to:
+  Settings -> Connectors -> API keys
+Then have the user create/copy the API key.
+
+If Granola did not come forward, run:
+  ${payload.granolaApiKeyCommand}
+Then navigate the visible Granola app to Settings -> Connectors -> API keys.
 
 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:
   ${payload.continueCommand} --messages-handle "<phone_or_apple_id>" --granola-api-key "<granola_key>"
@@ -692,6 +718,14 @@ function publicAgentAccount(account) {
   };
 }
 
+function authenticatedEmail(authenticated) {
+  return authenticated?.workosUser?.email ?? authenticated?.account?.email ?? null;
+}
+
+function authenticatedName(authenticated) {
+  return authenticated?.workosUser?.name ?? authenticated?.account?.name ?? null;
+}
+
 function agentNeedsUserAction(sources, opened) {
   const actions = [];
   if (sources.google && opened.includes("google")) actions.push("Complete Google browser authorization for Gmail, Docs, and Calendar consent.");
@@ -811,8 +845,8 @@ async function openOrPrint(url, opts) {
 async function openGranolaApiKeys(opts = {}) {
   const deepLink = "granola://settings/connectors/api-keys";
   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") {
@@ -821,21 +855,25 @@ 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 });
   }
 
   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: "Use local computer control to navigate Granola to Settings -> Connectors -> API keys.",
   };
 }
 

package/package.json

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