shepherd-onboard 0.1.4 → 0.1.5

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,9 +21,9 @@ 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
@@ -38,7 +38,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",
@@ -594,20 +615,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.
 
@@ -692,6 +713,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.");

package/package.json

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