workos 0.4.5 → 0.5.1

package/dist/vanilla-js/vanilla-js-installer-agent.js

@@ -1,47 +1,5 @@
-import { enableDebugLogs } from '../utils/debug.js';
-import { runAgentInstaller } from '../lib/agent-runner.js';
-import { Integration } from '../lib/constants.js';
-const VANILLA_JS_AGENT_CONFIG = {
-    metadata: {
-        name: 'Vanilla JavaScript',
-        integration: Integration.vanillaJs,
-        docsUrl: 'https://workos.com/docs/user-management/authkit/javascript',
-        unsupportedVersionDocsUrl: 'https://workos.com/docs/user-management/authkit/javascript',
-        skillName: 'workos-authkit-vanilla-js',
-    },
-    detection: {
-        packageName: 'workos',
-        packageDisplayName: 'Vanilla JavaScript',
-        getVersion: () => undefined,
-    },
-    environment: {
-        uploadToHosting: false,
-        requiresApiKey: false, // Client-only
-        getEnvVars: (apiKey, clientId) => ({
-            WORKOS_CLIENT_ID: clientId, // Only client ID needed
-        }),
-    },
-    analytics: {
-        getTags: () => ({}),
-    },
-    prompts: {},
-    ui: {
-        successMessage: 'WorkOS AuthKit integration complete',
-        getOutroChanges: () => [
-            'Created WorkOS AuthKit integration',
-            'Added authentication to your JavaScript application',
-            'Set up login/logout functionality',
-        ],
-        getOutroNextSteps: () => [
-            'Start your development server to test authentication',
-            'Visit the WorkOS Dashboard to manage users and settings',
-        ],
-    },
-};
-export async function runVanillaJsInstallerAgent(options) {
-    if (options.debug) {
-        enableDebugLogs();
-    }
-    return runAgentInstaller(VANILLA_JS_AGENT_CONFIG, options);
-}
+/**
+ * @deprecated Import from 'src/integrations/vanilla-js/index.js' instead.
+ */
+export { run as runVanillaJsInstallerAgent, config as VANILLA_JS_AGENT_CONFIG, } from '../integrations/vanilla-js/index.js';
 //# sourceMappingURL=vanilla-js-installer-agent.js.map

package/dist/vanilla-js/vanilla-js-installer-agent.js.map

@@ -1 +1 @@
-{"version":3,"file":"vanilla-js-installer-agent.js","sourceRoot":"","sources":["../../src/vanilla-js/vanilla-js-installer-agent.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAElD,MAAM,uBAAuB,GAAoB;IAC/C,QAAQ,EAAE;QACR,IAAI,EAAE,oBAAoB;QAC1B,WAAW,EAAE,WAAW,CAAC,SAAS;QAClC,OAAO,EAAE,4DAA4D;QACrE,yBAAyB,EAAE,4DAA4D;QACvF,SAAS,EAAE,2BAA2B;KACvC;IAED,SAAS,EAAE;QACT,WAAW,EAAE,QAAQ;QACrB,kBAAkB,EAAE,oBAAoB;QACxC,UAAU,EAAE,GAAG,EAAE,CAAC,SAAS;KAC5B;IAED,WAAW,EAAE;QACX,eAAe,EAAE,KAAK;QACtB,cAAc,EAAE,KAAK,EAAE,cAAc;QACrC,UAAU,EAAE,CAAC,MAAc,EAAE,QAAgB,EAAE,EAAE,CAAC,CAAC;YACjD,gBAAgB,EAAE,QAAQ,EAAE,wBAAwB;SACrD,CAAC;KACH;IAED,SAAS,EAAE;QACT,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC;KACpB;IAED,OAAO,EAAE,EAAE;IAEX,EAAE,EAAE;QACF,cAAc,EAAE,qCAAqC;QACrD,eAAe,EAAE,GAAG,EAAE,CAAC;YACrB,oCAAoC;YACpC,qDAAqD;YACrD,mCAAmC;SACpC;QACD,iBAAiB,EAAE,GAAG,EAAE,CAAC;YACvB,sDAAsD;YACtD,yDAAyD;SAC1D;KACF;CACF,CAAC;AAEF,MAAM,CAAC,KAAK,UAAU,0BAA0B,CAAC,OAAyB;IACxE,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;QAClB,eAAe,EAAE,CAAC;IACpB,CAAC;IAED,OAAO,iBAAiB,CAAC,uBAAuB,EAAE,OAAO,CAAC,CAAC;AAC7D,CAAC","sourcesContent":["/* Vanilla JS wizard using Claude Agent SDK */\nimport type { InstallerOptions } from '../utils/types.js';\nimport type { FrameworkConfig } from '../lib/framework-config.js';\nimport { enableDebugLogs } from '../utils/debug.js';\nimport { runAgentInstaller } from '../lib/agent-runner.js';\nimport { Integration } from '../lib/constants.js';\n\nconst VANILLA_JS_AGENT_CONFIG: FrameworkConfig = {\n  metadata: {\n    name: 'Vanilla JavaScript',\n    integration: Integration.vanillaJs,\n    docsUrl: 'https://workos.com/docs/user-management/authkit/javascript',\n    unsupportedVersionDocsUrl: 'https://workos.com/docs/user-management/authkit/javascript',\n    skillName: 'workos-authkit-vanilla-js',\n  },\n\n  detection: {\n    packageName: 'workos',\n    packageDisplayName: 'Vanilla JavaScript',\n    getVersion: () => undefined,\n  },\n\n  environment: {\n    uploadToHosting: false,\n    requiresApiKey: false, // Client-only\n    getEnvVars: (apiKey: string, clientId: string) => ({\n      WORKOS_CLIENT_ID: clientId, // Only client ID needed\n    }),\n  },\n\n  analytics: {\n    getTags: () => ({}),\n  },\n\n  prompts: {},\n\n  ui: {\n    successMessage: 'WorkOS AuthKit integration complete',\n    getOutroChanges: () => [\n      'Created WorkOS AuthKit integration',\n      'Added authentication to your JavaScript application',\n      'Set up login/logout functionality',\n    ],\n    getOutroNextSteps: () => [\n      'Start your development server to test authentication',\n      'Visit the WorkOS Dashboard to manage users and settings',\n    ],\n  },\n};\n\nexport async function runVanillaJsInstallerAgent(options: InstallerOptions): Promise<string> {\n  if (options.debug) {\n    enableDebugLogs();\n  }\n\n  return runAgentInstaller(VANILLA_JS_AGENT_CONFIG, options);\n}\n"]}
+{"version":3,"file":"vanilla-js-installer-agent.js","sourceRoot":"","sources":["../../src/vanilla-js/vanilla-js-installer-agent.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EACL,GAAG,IAAI,0BAA0B,EACjC,MAAM,IAAI,uBAAuB,GAClC,MAAM,qCAAqC,CAAC","sourcesContent":["/**\n * @deprecated Import from 'src/integrations/vanilla-js/index.js' instead.\n */\nexport {\n  run as runVanillaJsInstallerAgent,\n  config as VANILLA_JS_AGENT_CONFIG,\n} from '../integrations/vanilla-js/index.js';\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "workos",
-  "version": "0.4.5",
+  "version": "0.5.1",
   "type": "module",
   "description": "The Official Workos CLI",
   "repository": {
@@ -73,8 +73,7 @@
   "engines": {
     "node": ">=20.20"
   },
-  "author": "WorkOS",
-  "license": "MIT",
+  "packageManager": "pnpm@10.28.2",
   "scripts": {
     "clean": "rm -rf ./dist",
     "prebuild": "pnpm clean",
@@ -95,5 +94,7 @@
     "eval:prune": "tsx tests/evals/index.ts prune",
     "eval:logs": "tsx tests/evals/index.ts logs",
     "eval:show": "tsx tests/evals/index.ts show"
-  }
-}
+  },
+  "author": "WorkOS",
+  "license": "MIT"
+}

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

@@ -35,21 +35,39 @@ Detect package manager, install SDK package from README.
 
 **Verify:** SDK package exists in node_modules before continuing.
 
-## Step 4: Version Detection (Decision Tree)
+## Step 4: Locate the app/ directory (BLOCKING)
+
+**STOP. Do this before creating any files.**
+
+Determine where the `app/` directory lives:
+
+```bash
+# Check for src/app/ first, then root app/
+ls src/app/ 2>/dev/null && echo "APP_DIR=src" || (ls app/ 2>/dev/null && echo "APP_DIR=root")
+```
+
+Set `APP_DIR` for all subsequent steps. All middleware/proxy files MUST be created in `APP_DIR`:
+
+- If `APP_DIR=src` → create files in `src/` (e.g., `src/proxy.ts`)
+- If `APP_DIR=root` → create files at project root (e.g., `proxy.ts`)
+
+Next.js only discovers middleware/proxy files in the parent directory of `app/`. A file at the wrong level is **silently ignored** — no error, just doesn't run.
+
+## Step 5: Version Detection (Decision Tree)
 
 Read Next.js version from `package.json`:
 
 ```
 Next.js version?
   |
-  +-- 16+ --> Create proxy.ts at project root
+  +-- 16+ --> Create {APP_DIR}/proxy.ts
   |
-  +-- 15   --> Create middleware.ts (cookies() is async - handlers must await)
+  +-- 15   --> Create {APP_DIR}/middleware.ts (cookies() is async)
   |
-  +-- 13-14 --> Create middleware.ts (cookies() is sync)
+  +-- 13-14 --> Create {APP_DIR}/middleware.ts (cookies() is sync)
 ```
 
-**Critical:** File MUST be at project root (or `src/` if using src directory). Never in `app/`.
+**Next.js 16+ proxy.ts:** `proxy.ts` is the preferred convention. `middleware.ts` still works but shows a deprecation warning. Next.js 16 throws **error E900** if both files exist at the same level.
 
 **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.
 
@@ -95,14 +113,14 @@ export default async function middleware(request: NextRequest) {
 
 **Critical:** Always return via `handleAuthkitHeaders()` to ensure `withAuth()` works in pages.
 
-## Step 5: Create Callback Route
+## Step 6: Create Callback Route
 
 Parse `NEXT_PUBLIC_WORKOS_REDIRECT_URI` to determine route path:
 
 ```
-URI path          --> Route location
-/auth/callback    --> app/auth/callback/route.ts
-/callback         --> app/callback/route.ts
+URI path          --> Route location (use APP_DIR from Step 4)
+/auth/callback    --> {APP_DIR}/app/auth/callback/route.ts
+/callback         --> {APP_DIR}/app/callback/route.ts
 ```
 
 Use `handleAuth()` from SDK. Do not write custom OAuth logic.
@@ -118,7 +136,7 @@ export const GET = handleAuth();
 
 Check README for exact usage. If build fails with "cookies outside request scope", the handler is likely missing async/await.
 
-## Step 6: Provider Setup (REQUIRED)
+## Step 7: Provider Setup (REQUIRED)
 
 **CRITICAL:** You MUST wrap the app in `AuthKitProvider` in `app/layout.tsx`.
 
@@ -147,7 +165,7 @@ Check README for exact import path - it may be a subpath export like `@workos-in
 
 **Do NOT skip this step** even if using server-side auth patterns elsewhere.
 
-## Step 7: UI Integration
+## Step 8: UI Integration
 
 Add auth UI to `app/page.tsx` using SDK functions. See README for `getUser`, `getSignInUrl`, `signOut` usage.
 
@@ -191,6 +209,18 @@ This error causes OAuth codes to expire ("invalid_grant"), so fix the handler fi
 - 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)
 
+### "Both middleware file and proxy file are detected" (Next.js 16+)
+
+- Next.js 16 throws error E900 if both `middleware.ts` and `proxy.ts` exist
+- Delete `middleware.ts` and use only `proxy.ts`
+- If `middleware.ts` has custom logic, migrate it into `proxy.ts`
+
+### "withAuth route not covered by middleware" but middleware/proxy file exists
+
+- **Most common cause:** File is at the wrong level. Next.js only discovers middleware/proxy files in the parent directory of `app/`. For `src/app/` projects, the file must be in `src/`, not at the project root.
+- Check: Is `app/` at `src/app/`? Then middleware/proxy must be at `src/middleware.ts` or `src/proxy.ts`
+- Check: Matcher config must include the route path being accessed
+
 ### "Cannot use getUser in client component"
 
 - Check: Component has no `'use client'` directive, or

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

@@ -0,0 +1,160 @@
+---
+name: workos-authkit-sveltekit
+description: Integrate WorkOS AuthKit with SvelteKit. Server-side authentication with hooks and file-based routing.
+---
+
+# WorkOS AuthKit for SvelteKit
+
+## Step 1: Fetch SDK Documentation (BLOCKING)
+
+**STOP. Do not proceed until complete.**
+
+WebFetch: `https://github.com/workos/authkit-sveltekit/blob/main/README.md`
+
+The README is the source of truth. If this skill conflicts with README, follow README.
+
+## Step 2: Pre-Flight Validation
+
+### Project Structure
+
+- Confirm `svelte.config.js` (or `svelte.config.ts`) exists
+- Confirm `package.json` contains `@sveltejs/kit` dependency
+- Confirm `src/routes/` directory exists
+
+### Environment Variables
+
+Check `.env` or `.env.local` for:
+
+- `WORKOS_API_KEY` - starts with `sk_`
+- `WORKOS_CLIENT_ID` - starts with `client_`
+- `WORKOS_REDIRECT_URI` - valid callback URL
+- `WORKOS_COOKIE_PASSWORD` - 32+ characters
+
+SvelteKit uses `$env/static/private` and `$env/dynamic/private` natively. The agent should write env vars to `.env` (SvelteKit's default) or `.env.local`.
+
+## Step 3: Install SDK
+
+Detect package manager, install SDK package from README.
+
+```
+pnpm-lock.yaml? → pnpm add @workos-inc/authkit-sveltekit
+yarn.lock? → yarn add @workos-inc/authkit-sveltekit
+bun.lockb? → bun add @workos-inc/authkit-sveltekit
+else → npm install @workos-inc/authkit-sveltekit
+```
+
+**Verify:** SDK package exists in node_modules before continuing.
+
+## Step 4: Configure Server Hooks
+
+SvelteKit uses `src/hooks.server.ts` for server-side middleware. This is where the AuthKit handler is registered.
+
+Create or update `src/hooks.server.ts` with the authkit handle function from the README.
+
+### Existing Hooks (IMPORTANT)
+
+If `src/hooks.server.ts` already exists with custom logic, use SvelteKit's `sequence()` helper to compose hooks:
+
+```typescript
+import { sequence } from '@sveltejs/kit/hooks';
+import { authkitHandle } from '@workos-inc/authkit-sveltekit'; // Check README for exact export
+
+export const handle = sequence(authkitHandle, yourExistingHandle);
+```
+
+Check README for the exact export name and usage pattern.
+
+## Step 5: Create Callback Route
+
+Parse `WORKOS_REDIRECT_URI` to determine route path:
+
+```
+URI path          --> Route location
+/callback         --> src/routes/callback/+server.ts
+/auth/callback    --> src/routes/auth/callback/+server.ts
+```
+
+Use the SDK's callback handler from the README. Do not write custom OAuth logic.
+
+**Critical:** SvelteKit uses `+server.ts` for API routes, not `+page.server.ts`.
+
+## Step 6: Layout Setup
+
+Update `src/routes/+layout.server.ts` to load the auth session and pass it to all pages.
+
+Check README for the exact pattern — typically a `load` function that returns the user session from locals.
+
+```typescript
+// src/routes/+layout.server.ts
+import type { LayoutServerLoad } from './$types';
+
+export const load: LayoutServerLoad = async (event) => {
+  // Check README for exact API — session is typically on event.locals
+  return {
+    user: event.locals.user, // or similar from README
+  };
+};
+```
+
+## Step 7: UI Integration
+
+Add auth UI to `src/routes/+page.svelte` using the session data from the layout.
+
+- Show user info when authenticated
+- Show sign-in link/button when not authenticated
+- Add sign-out functionality
+
+Check README for sign-in URL generation and sign-out patterns.
+
+## Verification Checklist (ALL MUST PASS)
+
+Run these commands to confirm integration. **Do not mark complete until all pass:**
+
+```bash
+# 1. Check hooks.server.ts exists and has authkit
+grep -i "workos\|authkit" src/hooks.server.ts || echo "FAIL: authkit missing from hooks.server.ts"
+
+# 2. Check callback route exists
+find src/routes -name "+server.ts" -path "*/callback/*"
+
+# 3. Check layout loads auth session
+grep -i "user\|auth\|session" src/routes/+layout.server.ts || echo "FAIL: auth session missing from layout"
+
+# 4. Build succeeds
+pnpm build || npm run build
+```
+
+## Error Recovery
+
+### "Cannot find module '@workos-inc/authkit-sveltekit'"
+
+- Check: SDK installed before writing imports
+- Check: SDK package directory exists in node_modules
+- Re-run install if missing
+
+### hooks.server.ts not taking effect
+
+- Check: File is at `src/hooks.server.ts`, not `src/hooks.ts` or elsewhere
+- Check: Named export is `handle` (SvelteKit requirement)
+- Check: If using `sequence()`, all handles are properly composed
+
+### Callback route not found (404)
+
+- Check: File uses `+server.ts` (not `+page.server.ts`)
+- Check: Route path matches `WORKOS_REDIRECT_URI` path exactly
+- Check: Exports `GET` handler (SvelteKit convention)
+
+### "locals" type errors
+
+- Check: App.Locals interface is augmented in `src/app.d.ts`
+- Check README for TypeScript setup instructions
+
+### Cookie password error
+
+- Verify `WORKOS_COOKIE_PASSWORD` is 32+ characters
+- Generate new: `openssl rand -base64 32`
+
+### Auth state not available in pages
+
+- Check: `+layout.server.ts` load function returns user data
+- Check: Pages access data via `export let data` (Svelte 4) or `$page.data` (Svelte 5)

package/skills/workos-dotnet/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: workos-dotnet
+description: Integrate WorkOS AuthKit with .NET (ASP.NET Core). Backend authentication with DI registration, auth endpoints, and appsettings configuration.
+---
+
+# WorkOS AuthKit for .NET (ASP.NET Core)
+
+## Step 1: Fetch SDK Documentation (BLOCKING)
+
+**STOP. Do not proceed until complete.**
+
+WebFetch: `https://raw.githubusercontent.com/workos/workos-dotnet/main/README.md`
+
+The README is the source of truth for SDK API usage. If this skill conflicts with README, follow README.
+
+## Step 2: Pre-Flight Validation
+
+### Project Structure
+
+- Confirm a `*.csproj` file exists in the project root
+- Detect project style:
+  - **Minimal API** (modern): `Program.cs` with `WebApplication.CreateBuilder()` — .NET 6+
+  - **Startup pattern** (older): `Startup.cs` with `ConfigureServices()` / `Configure()` — .NET 5 and earlier
+
+This detection determines WHERE to register WorkOS services and middleware.
+
+### Environment Variables
+
+Check `appsettings.Development.json` for:
+
+- `WORKOS_API_KEY` — starts with `sk_`
+- `WORKOS_CLIENT_ID` — starts with `client_`
+
+## Step 3: Install SDK
+
+```bash
+dotnet add package WorkOS.net
+```
+
+**Verify:** Check the `*.csproj` file contains a `<PackageReference Include="WorkOS.net"` entry.
+
+If `dotnet` CLI is not available, stop and inform the user to install the .NET SDK.
+
+## Step 4: Configure WorkOS Client
+
+### Minimal API Pattern (Program.cs)
+
+Add WorkOS configuration to `Program.cs`:
+
+1. Read WorkOS settings from `IConfiguration`
+2. Register the WorkOS client in the DI container
+3. The WorkOS client needs API key for initialization
+
+```csharp
+// In Program.cs, after builder creation:
+var workosApiKey = builder.Configuration["WorkOS:ApiKey"];
+var workosClientId = builder.Configuration["WorkOS:ClientId"];
+```
+
+### Startup Pattern (Startup.cs)
+
+Add to `ConfigureServices()`:
+
+1. Read WorkOS settings from `IConfiguration`
+2. Register services
+
+Choose the pattern that matches the detected project structure.
+
+## Step 5: Create Authentication Endpoints
+
+Create auth endpoints following the WorkOS AuthKit pattern. Use minimal API `app.MapGet()` for minimal API projects, or a Controller for Startup-pattern projects.
+
+### Required Endpoints
+
+**GET /auth/login** — Redirect to WorkOS AuthKit:
+
+- Use the WorkOS SDK to generate an authorization URL
+- Include `clientId`, `redirectUri`, and `provider: "authkit"` parameters
+- Redirect the user to the authorization URL
+
+**GET /auth/callback** — Handle OAuth callback:
+
+- Extract `code` from query parameters
+- Exchange authorization code for user profile using the WorkOS SDK
+- Store user info in session or cookie
+- Redirect to home page
+
+**GET /auth/logout** — Clear session:
+
+- Clear the authentication session/cookie
+- Redirect to home page
+
+### Session Management
+
+Use ASP.NET Core's built-in session or cookie authentication:
+
+```csharp
+// Enable session middleware in Program.cs
+builder.Services.AddDistributedMemoryCache();
+builder.Services.AddSession();
+// ...
+app.UseSession();
+```
+
+## Step 6: Environment Setup
+
+Configure `appsettings.Development.json` with WorkOS credentials:
+
+```json
+{
+  "WorkOS": {
+    "ApiKey": "<WORKOS_API_KEY value>",
+    "ClientId": "<WORKOS_CLIENT_ID value>",
+    "RedirectUri": "http://localhost:5000/auth/callback"
+  }
+}
+```
+
+Use the actual credential values provided in the environment context.
+
+**Important:** Do NOT put secrets in `appsettings.json` (committed to git). Use `appsettings.Development.json` (gitignored) or `dotnet user-secrets`.
+
+## Step 7: Verification
+
+Run these checks — **do not mark complete until all pass:**
+
+```bash
+# 1. Check WorkOS.net is in csproj
+grep -i "WorkOS" *.csproj
+
+# 2. Check auth endpoints exist
+grep -r "auth/login\|auth/callback\|auth/logout" *.cs
+
+# 3. Build succeeds
+dotnet build
+```
+
+**If build fails:** Read the error output carefully. Common issues:
+
+- Missing `using` statements for WorkOS namespaces
+- Incorrect DI registration order
+- Missing session/cookie middleware registration
+
+## Error Recovery
+
+### "dotnet: command not found"
+
+- .NET SDK is not installed. Inform the user to install from https://dotnet.microsoft.com/download
+
+### NuGet restore failures
+
+- Check internet connectivity
+- Try `dotnet restore` explicitly before `dotnet build`
+
+### "No project file found"
+
+- Ensure you're in the correct directory with a `*.csproj` file
+
+### Build errors after integration
+
+- Check that all `using` statements are correct
+- Verify DI registration order (services before middleware)
+- Ensure `app.UseSession()` is called before mapping auth endpoints