workos 0.1.1 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "workos",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "type": "module",
   "description": "The Official Workos CLI",
   "keywords": [
@@ -36,6 +36,7 @@
   },
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "~0.2.19",
+    "@anthropic-ai/sdk": "^0.71.2",
     "@clack/core": "^0.5.0",
     "@clack/prompts": "0.11.0",
     "chalk": "^5.6.2",
@@ -67,7 +68,8 @@
   "engines": {
     "node": ">=20.20"
   },
-  "packageManager": "pnpm@10.23.0+sha512.21c4e5698002ade97e4efe8b8b4a89a8de3c85a37919f957e7a0f30f38fbc5bbdd05980ffe29179b2fb6e6e691242e098d945d1601772cad0fef5fb6411e2a4b",
+  "author": "WorkOS",
+  "license": "MIT",
   "scripts": {
     "clean": "rm -rf ./dist",
     "prebuild": "pnpm clean",
@@ -81,7 +83,5 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit"
-  },
-  "author": "WorkOS",
-  "license": "MIT"
-}
+  }
+}

package/skills/workos-authkit-base/SKILL.md

@@ -17,14 +17,14 @@ README is the source of truth for: install commands, imports, API usage, code pa
 
 ## Task Structure (Required)
 
-| Phase | Task | Blocked By | Purpose |
-|-------|------|------------|---------|
-| 1 | preflight | - | Verify env vars, detect framework |
-| 2 | install | preflight | Install SDK package |
-| 3 | callback | install | Create OAuth callback route |
-| 4 | provider | install | Setup auth context/middleware |
-| 5 | ui | callback, provider | Add sign-in/out UI |
-| 6 | verify | ui | Build confirmation |
+| Phase | Task      | Blocked By         | Purpose                           |
+| ----- | --------- | ------------------ | --------------------------------- |
+| 1     | preflight | -                  | Verify env vars, detect framework |
+| 2     | install   | preflight          | Install SDK package               |
+| 3     | callback  | install            | Create OAuth callback route       |
+| 4     | provider  | install            | Setup auth context/middleware     |
+| 5     | ui        | callback, provider | Add sign-in/out UI                |
+| 6     | verify    | ui                 | Build confirmation                |
 
 ## Decision Trees
 
@@ -51,57 +51,67 @@ Extract path from `WORKOS_REDIRECT_URI` → create route at that exact path.
 
 ## Environment Variables
 
-| Variable | Purpose | When Required |
-|----------|---------|---------------|
-| `WORKOS_API_KEY` | Server authentication | Server SDKs |
-| `WORKOS_CLIENT_ID` | Client identification | All SDKs |
-| `WORKOS_REDIRECT_URI` | OAuth callback URL | Server SDKs |
-| `WORKOS_COOKIE_PASSWORD` | Session encryption (32+ chars) | Server SDKs |
+| Variable                 | Purpose                        | When Required |
+| ------------------------ | ------------------------------ | ------------- |
+| `WORKOS_API_KEY`         | Server authentication          | Server SDKs   |
+| `WORKOS_CLIENT_ID`       | Client identification          | All SDKs      |
+| `WORKOS_REDIRECT_URI`    | OAuth callback URL             | Server SDKs   |
+| `WORKOS_COOKIE_PASSWORD` | Session encryption (32+ chars) | Server SDKs   |
 
 Note: Some frameworks use prefixed variants (e.g., `NEXT_PUBLIC_*`). Check README.
 
 ## Verification Checklists
 
 ### After Install
+
 - [ ] SDK package installed in node_modules
 - [ ] No install errors in output
 
 ### After Callback Route
+
 - [ ] Route file exists at path matching `WORKOS_REDIRECT_URI`
 - [ ] Imports SDK callback handler (not custom OAuth)
 
 ### After Provider/Middleware
+
 - [ ] Provider wraps entire app (client-side)
 - [ ] Middleware configured in correct location (server-side)
 
 ### After UI
+
 - [ ] Home page shows conditional auth state
 - [ ] Uses SDK functions for sign-in/out URLs
 
 ### Final Verification
+
 - [ ] Build completes with exit code 0
 - [ ] No import resolution errors
 
 ## Error Recovery
 
 ### Module not found
+
 - [ ] Verify install completed successfully
 - [ ] Verify SDK exists in node_modules
 - [ ] Re-run install if missing
 
 ### Build import errors
+
 - [ ] Delete `node_modules`, reinstall
 - [ ] Verify package.json has SDK dependency
 
 ### Invalid redirect URI
+
 - [ ] Compare route path to `WORKOS_REDIRECT_URI`
 - [ ] Paths must match exactly
 
 ### Cookie password error
+
 - [ ] Verify `WORKOS_COOKIE_PASSWORD` is 32+ characters
 - [ ] Generate new: `openssl rand -base64 32`
 
 ### Auth state not persisting
+
 - [ ] Verify provider wraps entire app
 - [ ] Check middleware is in correct location
 

package/skills/workos-authkit-nextjs/SKILL.md

@@ -16,11 +16,14 @@ The README is the source of truth. If this skill conflicts with README, follow R
 ## Step 2: Pre-Flight Validation
 
 ### Project Structure
+
 - Confirm `next.config.js` or `next.config.mjs` exists
 - Confirm `package.json` contains `"next"` dependency
 
 ### Environment Variables
+
 Check `.env.local` for:
+
 - `WORKOS_API_KEY` - starts with `sk_`
 - `WORKOS_CLIENT_ID` - starts with `client_`
 - `NEXT_PUBLIC_WORKOS_REDIRECT_URI` - valid callback URL
@@ -41,11 +44,15 @@ Next.js version?
   |
   +-- 16+ --> Create proxy.ts at project root
   |
-  +-- 13-15 --> Create middleware.ts at project root
+  +-- 15   --> Create middleware.ts (cookies() is async - handlers must await)
+  |
+  +-- 13-14 --> Create middleware.ts (cookies() is sync)
 ```
 
 **Critical:** File MUST be at project root (or `src/` if using src directory). Never in `app/`.
 
+**Next.js 15+ async note:** All route handlers and middleware accessing cookies must be async and properly await cookie operations. This is a breaking change from Next.js 14.
+
 Middleware/proxy code: See README for `authkitMiddleware()` export pattern.
 
 ## Step 5: Create Callback Route
@@ -60,6 +67,17 @@ URI path          --> Route location
 
 Use `handleAuth()` from SDK. Do not write custom OAuth logic.
 
+**CRITICAL for Next.js 15+:** The route handler MUST be async and properly await handleAuth():
+
+```typescript
+// CORRECT - Next.js 15+ requires async route handlers
+export const GET = handleAuth();
+
+// If handleAuth returns a function, ensure it's awaited in request context
+```
+
+Check README for exact usage. If build fails with "cookies outside request scope", the handler is likely missing async/await.
+
 ## Step 6: Provider Setup
 
 Wrap app in `AuthKitProvider` in `app/layout.tsx`. See README for import path.
@@ -90,26 +108,45 @@ All checks must pass before marking complete.
 
 ## Error Recovery
 
+### "cookies was called outside a request scope" (Next.js 15+)
+
+**Most common cause:** Route handler not properly async or missing await.
+
+Fix for callback route:
+
+1. Check that `handleAuth()` is exported directly: `export const GET = handleAuth();`
+2. If using custom wrapper, ensure it's `async` and awaits any cookie operations
+3. Verify authkit-nextjs SDK version supports Next.js 15+ (check README for compatibility)
+4. **Never** call `cookies()` at module level - only inside request handlers
+
+This error causes OAuth codes to expire ("invalid_grant"), so fix the handler first.
+
 ### "middleware.ts not found"
+
 - Check: File at project root or `src/`, not inside `app/`
 - Check: Filename matches Next.js version (proxy.ts for 16+, middleware.ts for 13-15)
 
 ### "Cannot use getUser in client component"
+
 - Check: Component has no `'use client'` directive, or
 - Check: Move auth logic to server component/API route
 
 ### "Module not found" for SDK import
+
 - Check: SDK installed before writing imports
 - Check: SDK package directory exists in node_modules
 
 ### "withAuth route not covered by middleware"
+
 - Check: Middleware/proxy file exists at correct location
 - Check: Matcher config includes the route path
 
 ### Build fails after AuthKitProvider
+
 - Check: README for correct import path (may be subpath export)
 - Check: No client/server boundary violations
 
-### NEXT_PUBLIC_ prefix issues
+### NEXT*PUBLIC* prefix issues
+
 - Client components need `NEXT_PUBLIC_*` prefix
 - Server components use plain env var names

package/skills/workos-authkit-react/SKILL.md

@@ -27,10 +27,10 @@ START
 
 ## Critical: Build Tool Detection
 
-| Marker File | Build Tool | Env Prefix | Access Pattern |
-|-------------|------------|------------|----------------|
-| `vite.config.ts` | Vite | `VITE_` | `import.meta.env.VITE_*` |
-| `craco.config.js` or none | CRA | `REACT_APP_` | `process.env.REACT_APP_*` |
+| Marker File               | Build Tool | Env Prefix   | Access Pattern            |
+| ------------------------- | ---------- | ------------ | ------------------------- |
+| `vite.config.ts`          | Vite       | `VITE_`      | `import.meta.env.VITE_*`  |
+| `craco.config.js` or none | CRA        | `REACT_APP_` | `process.env.REACT_APP_*` |
 
 **Wrong prefix = undefined values at runtime.** This is the #1 integration failure.
 

package/skills/workos-authkit-react-router/SKILL.md

@@ -24,14 +24,15 @@ The README is the source of truth. If this skill conflicts with README, **follow
 
 ## Phase 2: Detect Router Mode
 
-| Mode           | Detection Signal                | Key Indicator               |
-| -------------- | ------------------------------- | --------------------------- |
-| v7 Framework   | `react-router.config.ts` exists | Routes in `app/routes/`     |
-| v7 Data        | `createBrowserRouter` in source | Loaders in route config     |
-| v7 Declarative | `<BrowserRouter>` component     | Routes as JSX, no loaders   |
-| v6             | package.json version `"6.x"`    | Similar to v7 Declarative   |
+| Mode           | Detection Signal                | Key Indicator             |
+| -------------- | ------------------------------- | ------------------------- |
+| v7 Framework   | `react-router.config.ts` exists | Routes in `app/routes/`   |
+| v7 Data        | `createBrowserRouter` in source | Loaders in route config   |
+| v7 Declarative | `<BrowserRouter>` component     | Routes as JSX, no loaders |
+| v6             | package.json version `"6.x"`    | Similar to v7 Declarative |
 
 **Detection order:**
+
 1. Check for `react-router.config.ts` (Framework mode)
 2. Grep for `createBrowserRouter` (Data mode)
 3. Check package.json version (v6 vs v7)
@@ -45,10 +46,10 @@ Based on detected mode, apply the corresponding README section. The README conta
 
 ### authLoader vs authkitLoader
 
-| Function       | Purpose                          | Where to use            |
-| -------------- | -------------------------------- | ----------------------- |
-| `authLoader`   | OAuth callback handler           | Callback route ONLY     |
-| `authkitLoader`| Fetch user data in routes        | Any route needing auth  |
+| Function        | Purpose                   | Where to use           |
+| --------------- | ------------------------- | ---------------------- |
+| `authLoader`    | OAuth callback handler    | Callback route ONLY    |
+| `authkitLoader` | Fetch user data in routes | Any route needing auth |
 
 **Common mistake:** Using `authkitLoader` for callback route. Use `authLoader()`.
 

package/skills/workos-authkit-tanstack-start/SKILL.md

@@ -27,6 +27,7 @@ description: Integrate WorkOS AuthKit with TanStack Start applications. Full-sta
 WebFetch: `https://github.com/workos/authkit-tanstack-start/blob/main/README.md`
 
 From README, extract:
+
 1. Package name from install command (e.g., `pnpm add @workos/...`)
 2. Use that exact name for all imports
 
@@ -41,12 +42,12 @@ From README, extract:
 
 ## Environment Variables
 
-| Variable | Format | Required |
-|----------|--------|----------|
-| `WORKOS_API_KEY` | `sk_...` | Yes |
-| `WORKOS_CLIENT_ID` | `client_...` | Yes |
-| `WORKOS_REDIRECT_URI` | Full URL | Yes |
-| `WORKOS_COOKIE_PASSWORD` | 32+ chars | Yes |
+| Variable                 | Format       | Required |
+| ------------------------ | ------------ | -------- |
+| `WORKOS_API_KEY`         | `sk_...`     | Yes      |
+| `WORKOS_CLIENT_ID`       | `client_...` | Yes      |
+| `WORKOS_REDIRECT_URI`    | Full URL     | Yes      |
+| `WORKOS_COOKIE_PASSWORD` | 32+ chars    | Yes      |
 
 Generate password if missing: `openssl rand -base64 32`
 
@@ -71,6 +72,7 @@ Logout requires `signOut()` followed by redirect in a route loader. See README f
 ## Callback Route
 
 Path must match `WORKOS_REDIRECT_URI`. If URI is `/api/auth/callback`:
+
 - File: `app/routes/api/auth/callback.tsx`
 - Use `handleAuth()` from SDK - do not write custom OAuth logic
 

package/skills/workos-authkit-vanilla-js/SKILL.md

@@ -29,6 +29,7 @@ Has package.json with build tool (Vite, webpack, Parcel)?
 ### Step 4: Implement Per README
 
 Follow README examples for:
+
 - Client initialization
 - Sign in/out handlers
 - User state management
@@ -56,20 +57,21 @@ const authkit = await createClient(clientId);
 ## Environment Variables
 
 **Bundled projects only:**
+
 - Vite: `VITE_WORKOS_CLIENT_ID`
 - Webpack: `REACT_APP_WORKOS_CLIENT_ID` or custom
 - No `WORKOS_API_KEY` needed (client-side SDK)
 
 ## Error Recovery
 
-| Error | Cause | Fix |
-|-------|-------|-----|
-| `WorkOS is not defined` | CDN not loaded | Add script to `<head>` before your code |
-| `createClient is not a function` | Wrong import | npm: check import path; CDN: use `WorkOS.createClient` |
-| `clientId is required` | Undefined env var | Check env prefix matches build tool |
-| CORS errors | `file://` protocol | Use local dev server (`npx serve`) |
-| Popup blocked | Not user gesture | Call `signIn()` only from click handler |
-| Auth state lost | Token not persisted | Check localStorage in dev tools |
+| Error                            | Cause               | Fix                                                    |
+| -------------------------------- | ------------------- | ------------------------------------------------------ |
+| `WorkOS is not defined`          | CDN not loaded      | Add script to `<head>` before your code                |
+| `createClient is not a function` | Wrong import        | npm: check import path; CDN: use `WorkOS.createClient` |
+| `clientId is required`           | Undefined env var   | Check env prefix matches build tool                    |
+| CORS errors                      | `file://` protocol  | Use local dev server (`npx serve`)                     |
+| Popup blocked                    | Not user gesture    | Call `signIn()` only from click handler                |
+| Auth state lost                  | Token not persisted | Check localStorage in dev tools                        |
 
 ## Task Flow
 

package/dist/package.json

@@ -1,87 +0,0 @@
-{
-    "name": "workos",
-    "version": "0.1.0",
-    "type": "module",
-    "description": "The Official Workos CLI",
-    "keywords": [
-        "workos",
-        "authkit",
-        "authentication",
-        "wizard",
-        "cli",
-        "setup",
-        "install",
-        "oauth",
-        "sso"
-    ],
-    "bin": {
-        "workos": "dist/bin.js"
-    },
-    "publishConfig": {
-        "access": "public"
-    },
-    "files": [
-        "dist/bin.*",
-        "dist/src",
-        "dist/cli.config.*",
-        ".claude-plugin",
-        "skills",
-        "package.json",
-        "README.md"
-    ],
-    "main": "dist/index.js",
-    "typings": "dist/index.d.ts",
-    "typescript": {
-        "definition": "dist/index.d.ts"
-    },
-    "dependencies": {
-        "@anthropic-ai/claude-agent-sdk": "~0.2.19",
-        "@clack/core": "^0.5.0",
-        "@clack/prompts": "0.11.0",
-        "chalk": "^5.6.2",
-        "diff": "^8.0.3",
-        "fast-glob": "^3.3.3",
-        "ink": "^6.6.0",
-        "opn": "^5.4.0",
-        "react": "^19.2.3",
-        "semver": "^7.7.3",
-        "uuid": "^13.0.0",
-        "xstate": "^5.25.1",
-        "yargs": "^18.0.0",
-        "zod": "^4.3.5"
-    },
-    "devDependencies": {
-        "@statelyai/inspect": "^0.4.0",
-        "@types/node": "~22.19.7",
-        "@types/opn": "5.1.0",
-        "@types/react": "^19.2.9",
-        "@types/semver": "^7.7.1",
-        "@types/yargs": "^17.0.35",
-        "@vitest/ui": "^4.0.17",
-        "dotenv": "^17.2.3",
-        "prettier": "^3.8.0",
-        "tsx": "^4.20.3",
-        "typescript": "^5.9.3",
-        "vitest": "^4.0.17"
-    },
-    "engines": {
-        "node": ">=20.20"
-    },
-    "packageManager": "pnpm@10.23.0+sha512.21c4e5698002ade97e4efe8b8b4a89a8de3c85a37919f957e7a0f30f38fbc5bbdd05980ffe29179b2fb6e6e691242e098d945d1601772cad0fef5fb6411e2a4b",
-    "scripts": {
-        "clean": "rm -rf ./dist",
-        "prebuild": "pnpm clean",
-        "build:watch": "pnpm tsc -w",
-        "build": "pnpm tsc",
-        "postbuild": "chmod +x ./dist/bin.js && cp -r scripts/** dist",
-        "lint": "prettier --check \"{lib,src,test}/**/*.ts\"",
-        "format": "prettier --write .",
-        "try": "tsx dev.ts",
-        "dev": "pnpm build && pnpm link --global && pnpm build:watch",
-        "test": "vitest run",
-        "test:watch": "vitest",
-        "typecheck": "tsc --noEmit"
-    },
-    "author": "WorkOS",
-    "license": "MIT"
-}