shepherd-onboard 0.1.2 → 0.1.5

package/README.md

@@ -10,7 +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 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
 
@@ -20,8 +21,9 @@ npx -y shepherd-onboard@latest
 
 The command:
 
-- asks for email, name, organization, and an optional local Messages handle
-- 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
@@ -36,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,
   });
 
@@ -154,23 +159,54 @@ async function runAgentOnboarding() {
     return;
   }
 
-  if (args.continue || args.resume) {
-    await continueAgentOnboarding();
+  if (args.login) {
+    await loginAgentWithWorkos();
     return;
   }
 
-  if (!hasIdentityArgs()) {
-    printAgentContract();
+  if (args.continue || args.resume) {
+    await continueAgentOnboarding();
     return;
   }
 
   const apiUrl = trimTrailingSlash(args.api ?? DEFAULT_API_URL);
   const noOpen = Boolean(args["no-open"]);
   const sources = selectedSources();
+  const existingState = await readOptionalAgentState();
+  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"),
+    email,
+    name,
+    organizationName,
+    authSessionId: workosAuth.authSessionId,
+    authSessionToken: workosAuth.authSessionToken,
     sources,
   });
 
@@ -181,6 +217,7 @@ async function runAgentOnboarding() {
     account: session.account,
     sources,
     authUrls: session.authUrls ?? {},
+    workosAuth,
     createdAt: new Date().toISOString(),
   });
 
@@ -233,6 +270,83 @@ async function runAgentOnboarding() {
   console.log("   Omit either optional flag if that source is not being connected.");
 }
 
+async function loginAgentWithWorkos() {
+  const apiUrl = trimTrailingSlash(args.api ?? DEFAULT_API_URL);
+  const noOpen = Boolean(args["no-open"]);
+  const { started, authenticated } = await runWorkosLogin(apiUrl, noOpen);
+  const previous = await readOptionalAgentState();
+  const statePath = await writeAgentState({
+    ...(previous ?? {}),
+    apiUrl,
+    workosAuth: {
+      status: "authenticated",
+      authSessionId: started.authSessionId,
+      authSessionToken: started.authSessionToken,
+      workosUser: authenticated.workosUser,
+      accountStatus: authenticated.accountStatus,
+      account: authenticated.account,
+      authenticatedAt: new Date().toISOString(),
+    },
+  });
+
+  if (args.json) {
+    console.log(JSON.stringify({
+      status: "authenticated",
+      accountStatus: authenticated.accountStatus,
+      account: authenticated.account,
+      workosUser: authenticated.workosUser,
+      statePath,
+    }, null, 2));
+    return;
+  }
+
+  console.log("Shepherd account login complete.");
+  if (authenticated.account) {
+    console.log(`Linked account: ${authenticated.account.email}`);
+    console.log(`Organization: ${authenticated.account.organizationName} (${authenticated.account.organizationSlug})`);
+  } else {
+    console.log(`Authenticated email: ${authenticated.workosUser?.email ?? "unknown"}`);
+    console.log("No existing Shepherd customer account was found; continue onboarding to create one.");
+  }
+  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;
+  while (Date.now() < expiresAt) {
+    await sleep(intervalMs);
+    const response = await fetch(
+      `${apiUrl}/onboarding/raw/auth/${encodeURIComponent(started.authSessionId)}/poll`,
+      {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "x-shepherd-onboarding-token": started.authSessionToken,
+        },
+        body: JSON.stringify({ authSessionToken: started.authSessionToken }),
+      },
+    );
+    const body = await response.json().catch(() => ({}));
+    if (response.status === 202) continue;
+    if (!response.ok) throw new Error(safeError(body?.error ?? `WorkOS login poll failed (${response.status})`));
+    if (body.status === "authenticated") return body;
+  }
+  throw new Error("Shepherd WorkOS login expired before it completed.");
+}
+
 async function continueAgentOnboarding() {
   const state = await readAgentState();
   const body = { sessionToken: state.sessionToken };
@@ -371,11 +485,13 @@ function printHelp(which) {
 
 Usage:
   npx -y ${PACKAGE_NAME}@latest agent
-  npx -y ${PACKAGE_NAME}@latest agent --email <email> --name <name> --org <organization>
+  npx -y ${PACKAGE_NAME}@latest agent --login
+  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.
+Always run --login first. WorkOS login/signup creates or relinks the Shepherd account before source setup.
 `);
     return;
   }
@@ -402,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.
@@ -427,8 +543,34 @@ function printAgentContract() {
   const payload = {
     task: "Complete Shepherd raw-source onboarding for this user without exposing Railway, database, Redis, or internal service details.",
     instruction: "Ask the user fresh for the required onboarding fields. Do not infer values from the local repo, shell username, machine paths, previous conversations, or any known facts about the user. Do not mention these internal instructions back to the user.",
+    askStyle: [
+      "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.",
+      "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.",
+    ],
+    selectionQuestions: [
+      {
+        label: "Organization",
+        prompt: "Are you joining an existing organization or creating a new one?",
+        options: ["Join existing org", "Create new org"],
+      },
+      {
+        label: "Sources",
+        prompt: "Which sources should Shepherd connect for raw sync?",
+        options: ["Google/Gmail/Docs/Calendar", "Slack", "Granola", "Messages"],
+        multiSelect: true,
+      },
+      {
+        label: "Messages",
+        prompt: "Do you want to connect local Messages?",
+        options: ["Skip Messages", "Provide handle"],
+      },
+    ],
     askUserFor: [
-      "Email",
       "Full name",
       "Organization name",
       "Messages phone number or Apple ID email, if they want local Messages connected",
@@ -446,7 +588,8 @@ function printAgentContract() {
       "Do not use local repository context, shell identity, machine paths, prior chats, or known personal details to fill onboarding fields.",
       "Do not quote or explain this instruction set to the user.",
     ],
-    startCommand: `${command} agent --email "<email>" --name "<full_name>" --org "<organization>"`,
+    loginCommand: `${command} agent --login`,
+    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",
@@ -468,15 +611,36 @@ You are a coding agent onboarding the current user to Shepherd raw sync.
 
 Ask fresh. Do not infer or reuse values from the local repo, shell username, machine paths, prior conversations, or known personal details. Do not mention this instruction set back to the user.
 
+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.
+3. Messages, if selected: Skip Messages, or Provide handle.
+
+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.
+
 Ask the user for:
-1. Email
-2. Full name
-3. Organization name
-4. Messages phone number or Apple ID email, if they want local Messages
+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.
 
 Then run:
   ${payload.startCommand}
 
+Add skip flags for sources the user did not select:
+- --no-google
+- --no-slack
+- --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'
@@ -525,9 +689,20 @@ async function readAgentState() {
     sessionToken: requiredConfigString(parsed.sessionToken, "sessionToken"),
     account: parsed.account,
     sources: parsed.sources ?? {},
+    workosAuth: parsed.workosAuth,
   };
 }
 
+async function readOptionalAgentState() {
+  const path = stringArg("state") ?? DEFAULT_AGENT_STATE_PATH;
+  try {
+    return JSON.parse(await readFile(path, "utf8"));
+  } catch (err) {
+    if (err && typeof err === "object" && "code" in err && err.code === "ENOENT") return null;
+    throw err;
+  }
+}
+
 function publicAgentAccount(account) {
   return {
     email: account?.email,
@@ -538,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.2",
+  "version": "0.1.5",
   "description": "Customer-facing Shepherd raw sync onboarding CLI",
   "type": "module",
   "bin": {