workos 0.9.0 → 0.10.1

package/skills/workos-elixir/SKILL.md

@@ -1,231 +0,0 @@
----
-name: workos-elixir
-description: Integrate WorkOS AuthKit with Elixir/Phoenix applications. Server-side authentication with Phoenix controllers and routes.
----
-
-# WorkOS AuthKit for Elixir (Phoenix)
-
-## Step 1: Fetch SDK Documentation (BLOCKING)
-
-**STOP. Do not proceed until complete.**
-
-WebFetch: `https://raw.githubusercontent.com/workos/workos-elixir/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 `mix.exs` exists
-- Read `mix.exs` to extract the app name (look for `app: :my_app` in `project/0`)
-- Confirm `lib/{app}_web/router.ex` exists (Phoenix project marker)
-- Confirm `config/runtime.exs` exists
-
-### Determine App Name
-
-The app name from `mix.exs` determines all file paths. For example, if `app: :my_app`:
-
-- Web module: `lib/my_app_web/`
-- Router: `lib/my_app_web/router.ex`
-- Controllers: `lib/my_app_web/controllers/`
-
-### Environment Variables
-
-Check `.env.local` for:
-
-- `WORKOS_API_KEY` - starts with `sk_`
-- `WORKOS_CLIENT_ID` - starts with `client_`
-
-## Step 2b: Partial Install Recovery
-
-Before creating new files, check if a previous AuthKit attempt exists:
-
-1. Check if `:workos` is already in `mix.exs` dependencies
-2. Check for incomplete auth code — AuthController exists but has TODO stubs, 501 responses, or missing callback/sign_out functions
-3. If partial install detected:
-   - Do NOT re-add the SDK dependency (it's already there)
-   - Do NOT re-run `mix deps.get` if deps are already fetched
-   - Read existing auth files to understand what's done vs missing
-   - Complete the integration by filling gaps (controller methods, routes)
-   - Preserve any working code — only fix what's broken
-   - Check for missing `/auth/callback` route (most common gap)
-
-## Step 2c: Existing Auth System Detection
-
-Check for existing authentication before integrating:
-
-```
-mix.exs has ':ueberauth'?                          → Ueberauth auth
-mix.exs has ':pow'?                                → Pow auth
-mix.exs has ':guardian'?                           → Guardian JWT auth
-mix.exs has ':phx_gen_auth'?                       → Phoenix generated auth
-config/*.exs has 'Ueberauth' config?               → Ueberauth configured
-router.ex has '/:provider' wildcard auth routes?   → Ueberauth routes
-```
-
-If existing auth detected:
-
-- Do NOT remove or disable it
-- Add WorkOS AuthKit alongside the existing system
-- If Ueberauth is configured, be careful of `/:provider` wildcard routes — use a specific scope like `/auth/workos` to avoid conflicts
-- Reuse existing session infrastructure if compatible
-- Create separate route paths for WorkOS auth
-- Ensure existing auth routes continue to work unchanged
-- Document in code comments how to migrate fully to WorkOS later
-
-## Step 3: Install SDK
-
-Add the `workos` package to `mix.exs` dependencies:
-
-```elixir
-defp deps do
-  [
-    # ... existing deps
-    {:workos, "~> 1.0"}
-  ]
-end
-```
-
-Then run:
-
-```bash
-mix deps.get
-```
-
-**Verify:** Check that `mix deps.get` completed successfully (exit code 0).
-
-## Step 4: Configure WorkOS
-
-Add WorkOS configuration to `config/runtime.exs`:
-
-```elixir
-config :workos,
-  api_key: System.get_env("WORKOS_API_KEY"),
-  client_id: System.get_env("WORKOS_CLIENT_ID")
-```
-
-This ensures credentials are loaded from environment variables at runtime, not compiled into the release.
-
-## Step 5: Create Auth Controller
-
-### Prerequisite: Verify `{AppName}Web` module exists
-
-The controller uses `use {AppName}Web, :controller`. Confirm `lib/{app}_web.ex` exists and defines the `:controller` macro. If it doesn't exist (minimal Phoenix projects may lack it), create it:
-
-```elixir
-defmodule {AppName}Web do
-  def controller do
-    quote do
-      use Phoenix.Controller, formats: [:html, :json]
-      import Plug.Conn
-    end
-  end
-
-  defmacro __using__(which) when is_atom(which) do
-    apply(__MODULE__, which, [])
-  end
-end
-```
-
-### Create controller
-
-Create `lib/{app}_web/controllers/auth_controller.ex`:
-
-```elixir
-defmodule {AppName}Web.AuthController do
-  use {AppName}Web, :controller
-
-  def sign_in(conn, _params) do
-    client_id = Application.get_env(:workos, :client_id)
-    redirect_uri = "http://localhost:4000/auth/callback"
-
-    authorization_url = WorkOS.UserManagement.get_authorization_url(%{
-      provider: "authkit",
-      client_id: client_id,
-      redirect_uri: redirect_uri
-    })
-
-    case authorization_url do
-      {:ok, url} -> redirect(conn, external: url)
-      {:error, reason} -> conn |> put_status(500) |> text("Auth error: #{inspect(reason)}")
-    end
-  end
-
-  def callback(conn, %{"code" => code}) do
-    client_id = Application.get_env(:workos, :client_id)
-
-    case WorkOS.UserManagement.authenticate_with_code(%{
-      code: code,
-      client_id: client_id
-    }) do
-      {:ok, auth_response} ->
-        conn
-        |> put_session(:user, auth_response.user)
-        |> redirect(to: "/")
-
-      {:error, reason} ->
-        conn |> put_status(401) |> text("Authentication failed: #{inspect(reason)}")
-    end
-  end
-
-  def sign_out(conn, _params) do
-    conn
-    |> clear_session()
-    |> redirect(to: "/")
-  end
-end
-```
-
-**IMPORTANT:** Adapt the module name and API calls based on the README. The WorkOS Elixir SDK API may differ from the pseudocode above. Always follow the README for exact function names, parameter shapes, and return types.
-
-## Step 6: Add Routes
-
-Add auth routes to `lib/{app}_web/router.ex`. Add these routes inside or outside the existing pipeline scope as appropriate:
-
-```elixir
-scope "/auth", {AppName}Web do
-  pipe_through :browser
-
-  get "/sign-in", AuthController, :sign_in
-  get "/callback", AuthController, :callback
-  post "/sign-out", AuthController, :sign_out
-end
-```
-
-## Step 7: Verification
-
-Run the following to confirm the integration compiles:
-
-```bash
-mix compile
-```
-
-**If compilation fails:**
-
-1. Read the error message carefully
-2. Check that the WorkOS SDK module names match what's in the README
-3. Verify the app name is consistent across all files
-4. Fix the issue and re-run `mix compile`
-
-## Error Recovery
-
-### "could not compile dependency :workos"
-
-- Check Elixir version compatibility (1.15+ recommended)
-- Try `mix deps.clean workos && mix deps.get`
-
-### "module WorkOS.UserManagement is not available"
-
-- The SDK API may use different module paths — re-read the README
-- Check if the SDK uses `WorkOS.SSO` or another module instead
-
-### "undefined function" in controller
-
-- Verify `use {AppName}Web, :controller` is correct
-- Check that the SDK functions match the README exactly
-
-### Route conflicts
-
-- Check existing routes in router.ex for `/auth` prefix conflicts
-- Adjust the scope path if needed (e.g., `/workos-auth`)

package/skills/workos-go/SKILL.md

@@ -1,226 +0,0 @@
----
-name: workos-go
-description: Integrate WorkOS AuthKit with Go applications. Supports Gin and stdlib net/http.
----
-
-# WorkOS AuthKit for Go
-
-## Step 1: Fetch SDK Documentation (BLOCKING)
-
-**STOP. Do not proceed until complete.**
-
-WebFetch: `https://raw.githubusercontent.com/workos/workos-go/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 `go.mod` exists in the project root
-- Confirm Go module is initialized (module path declared in `go.mod`)
-
-### Environment Variables
-
-Check `.env` for:
-
-- `WORKOS_API_KEY` - starts with `sk_`
-- `WORKOS_CLIENT_ID` - starts with `client_`
-- `WORKOS_REDIRECT_URI` - valid callback URL (e.g., `http://localhost:8080/auth/callback`)
-
-### Framework Detection
-
-Read `go.mod` to detect web framework:
-
-```
-go.mod contains github.com/gin-gonic/gin?
-  |
-  +-- Yes --> Use Gin router patterns
-  |
-  +-- No  --> Use stdlib net/http patterns
-```
-
-## Step 2b: Partial Install Recovery
-
-Before creating new files, check if a previous AuthKit attempt exists:
-
-1. Check if `github.com/workos/workos-go` is already in `go.mod`
-2. Check for incomplete auth code — files that import WorkOS packages but have non-functional handlers (TODO comments, 501 responses, empty handler bodies)
-3. If partial install detected:
-   - Do NOT re-run `go get` (the module is already there)
-   - Read existing auth files to understand what's done vs missing
-   - Complete the integration by filling gaps rather than starting fresh
-   - Preserve any working code — only fix what's broken
-   - If `usermanagement.SetAPIKey()` is already called in `init()`, don't call it again
-   - Always run `go mod tidy` after changes to keep `go.sum` consistent
-
-## Step 2c: Existing Auth System Detection
-
-Check for existing authentication before integrating:
-
-```
-*.go files have 'jwt' or 'JWT'?             → Custom JWT auth
-*.go files have 'oauth2'?                   → OAuth2 middleware
-*.go files have 'authMiddleware'?            → Custom auth middleware
-go.mod has 'golang.org/x/oauth2'?           → OAuth2 package
-go.mod has 'github.com/coreos/go-oidc'?     → OIDC auth
-```
-
-If existing auth detected:
-
-- Do NOT remove or disable it
-- Add WorkOS AuthKit alongside the existing system
-- Create separate route paths for WorkOS auth (e.g., `/auth/workos/login` if `/auth/login` is taken)
-- Match handler signatures to the detected framework (Gin `*gin.Context` vs stdlib `http.ResponseWriter, *http.Request`)
-- Ensure existing auth middleware continues to work on its routes
-- Document in code comments how to migrate fully to WorkOS later
-
-## Step 3: Install SDK
-
-Run:
-
-```bash
-go get github.com/workos/workos-go/v4
-```
-
-**Verify:** Check that `go.mod` now contains `github.com/workos/workos-go/v4`. Both `go.mod` and `go.sum` will be modified — this is expected.
-
-## Step 4: Configure Authentication
-
-### 4a: Create Auth Handler File
-
-Create an auth handler file. Respect existing project structure:
-
-- If `internal/` directory exists, create `internal/auth/handlers.go`
-- If `handlers/` directory exists, create `handlers/auth.go`
-- Otherwise, create `auth/handlers.go`
-
-The file must:
-
-- Declare a package matching the directory name
-- Import `github.com/workos/workos-go/v4` packages as needed
-- Read env vars with `os.Getenv("WORKOS_API_KEY")`, `os.Getenv("WORKOS_CLIENT_ID")`, `os.Getenv("WORKOS_REDIRECT_URI")`
-
-### 4b: Implement Handlers
-
-Implement these three handlers following the redirect-based auth flow from the README:
-
-**Login handler** (`/auth/login`):
-
-- Get the authorization URL from WorkOS using `usermanagement.GetAuthorizationURL()`
-- Set `Provider` to the string `"authkit"` (it's a plain string, not a constant)
-- Include `ClientID` and `RedirectURI` from env vars
-- Redirect the user to the returned URL
-
-**Callback handler** (`/auth/callback`):
-
-- Extract the `code` query parameter from the redirect
-- Call `usermanagement.AuthenticateWithCode()` with the code and `ClientID`
-- Store user info in session/cookie (or return as JSON for API-first apps)
-- Redirect to homepage or return user data
-
-**Logout handler** (`/auth/logout`):
-
-- Clear session data
-- Redirect to homepage
-
-**CRITICAL:** Use idiomatic Go error handling throughout:
-
-```go
-result, err := someFunction()
-if err != nil {
-    http.Error(w, "Error message", http.StatusInternalServerError)
-    return
-}
-```
-
-### 4c: Wire Handlers into Router
-
-#### If using Gin:
-
-```go
-r := gin.Default()
-r.GET("/auth/login", handleLogin)
-r.GET("/auth/callback", handleCallback)
-r.GET("/auth/logout", handleLogout)
-```
-
-#### If using stdlib net/http:
-
-```go
-http.HandleFunc("/auth/login", handleLogin)
-http.HandleFunc("/auth/callback", handleCallback)
-http.HandleFunc("/auth/logout", handleLogout)
-```
-
-Wire these routes into the existing router setup in `main.go` or wherever routes are defined. Do NOT replace existing routes — add alongside them.
-
-### 4d: Initialize WorkOS Client
-
-In the appropriate init location (package-level `init()` or `main()`), initialize the WorkOS client:
-
-```go
-import "github.com/workos/workos-go/v4/pkg/usermanagement"
-
-func init() {
-    usermanagement.SetAPIKey(os.Getenv("WORKOS_API_KEY"))
-}
-```
-
-Follow the README for the exact initialization pattern — it may differ from above.
-
-## Step 5: Environment Setup
-
-The `.env` file should already contain the required variables (written by the installer). Verify it contains:
-
-```
-WORKOS_API_KEY=sk_...
-WORKOS_CLIENT_ID=client_...
-WORKOS_REDIRECT_URI=http://localhost:8080/auth/callback
-```
-
-**Note for production:** Go does not have a built-in .env convention. In production, set real OS environment variables. The `.env` file is for development only. If using a `.env` loader like `github.com/joho/godotenv`, the agent may install it and add `godotenv.Load()` to `main()`.
-
-## Step 6: Verification
-
-Run these commands. **Do not mark complete until all pass:**
-
-```bash
-# 1. Go module is tidy
-go mod tidy
-
-# 2. Build succeeds
-go build ./...
-
-# 3. Vet passes (catches common mistakes)
-go vet ./...
-```
-
-If build fails:
-
-- Check import paths match the SDK version in `go.mod`
-- Ensure all new files have correct package declarations
-- Run `go mod tidy` to resolve dependency issues
-
-## Error Recovery
-
-### "cannot find module providing package github.com/workos/workos-go/v4/..."
-
-- Run `go mod tidy` to sync dependencies
-- Check that `go get` completed successfully
-- Verify the import path matches exactly (v4 suffix required)
-
-### "undefined: usermanagement.SetAPIKey" or similar
-
-- SDK API may have changed — refer to the fetched README
-- Check the correct subpackage import path
-
-### Build fails with type errors
-
-- Ensure handler function signatures match the framework (Gin uses `*gin.Context`, stdlib uses `http.ResponseWriter, *http.Request`)
-- Check that error return values are handled
-
-### "package X is not in std"
-
-- Run `go mod tidy` after adding new imports
-- Ensure `go get` was run before writing import statements

package/skills/workos-kotlin/SKILL.md

@@ -1,195 +0,0 @@
----
-name: workos-kotlin
-description: Integrate WorkOS AuthKit with Kotlin/Spring Boot. Backend authentication with Gradle.
----
-
-# WorkOS AuthKit for Kotlin (Spring Boot)
-
-## Step 1: Fetch SDK Documentation (BLOCKING)
-
-**STOP. Do not proceed until complete.**
-
-WebFetch: `https://raw.githubusercontent.com/workos/workos-kotlin/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 `build.gradle.kts` exists (Kotlin DSL) or `build.gradle` (Groovy DSL)
-- Confirm Spring Boot plugin is present (`org.springframework.boot`)
-- Detect Gradle wrapper: check if `./gradlew` exists
-
-### Gradle Wrapper
-
-```bash
-# If gradlew exists, ensure it's executable
-if [ -f ./gradlew ]; then chmod +x ./gradlew; fi
-```
-
-Use `./gradlew` if wrapper exists, otherwise fall back to `gradle`.
-
-### Environment Variables
-
-Check `application.properties` or `application.yml` for:
-
-- `workos.api-key` or `WORKOS_API_KEY`
-- `workos.client-id` or `WORKOS_CLIENT_ID`
-
-## Step 2b: Partial Install Recovery
-
-Before creating new files, check if a previous AuthKit attempt exists:
-
-1. Check if `workos-kotlin` is already in `build.gradle.kts` dependencies
-2. Check for incomplete auth code — WorkOS imported/instantiated but no controller with login/callback endpoints
-3. If partial install detected:
-   - Do NOT re-add the SDK dependency (it's already there)
-   - Read existing source files to understand what's done vs missing
-   - Complete the integration by filling gaps (controller, config bean, routes)
-   - Preserve any working code — only fix what's broken
-   - Check for a missing `/auth/callback` endpoint (most common gap)
-
-## Step 2c: Existing Auth System Detection
-
-Check for existing authentication before integrating:
-
-```
-build.gradle.kts has 'spring-boot-starter-security'?  → Spring Security
-*.kt files have 'SecurityFilterChain'?                → Security filter config
-*.kt files have 'formLogin'?                          → Form-based auth
-*.kt files have 'oauth2Login'?                        → OAuth2 auth
-*.kt files have 'httpBasic'?                          → Basic auth
-```
-
-If existing auth detected:
-
-- Do NOT remove or disable it
-- Add WorkOS AuthKit alongside the existing system
-- If Spring Security is configured, ensure WorkOS auth routes are permitted through the security filter chain (add `.requestMatchers("/auth/workos/**").permitAll()`)
-- Create separate route paths for WorkOS auth (e.g., `/auth/workos/login` if `/login` is taken)
-- Ensure existing auth routes continue to work unchanged
-- Document in code comments how to migrate fully to WorkOS later
-
-## Step 3: Install SDK
-
-Add the WorkOS Kotlin SDK dependency to `build.gradle.kts`:
-
-```kotlin
-dependencies {
-    implementation("com.workos:workos-kotlin:4.18.1")
-    // ... existing dependencies
-}
-```
-
-Check the README for the latest version number — use the version from the README if it differs from above.
-
-**JVM target**: Ensure `jvmTarget` in `build.gradle.kts` matches the JDK on the system. Check with `java -version`. Common values: `"17"`, `"21"`. If `kotlin { jvmToolchain(...) }` is set, ensure it matches too.
-
-**Verify:** Run `./gradlew dependencies` or `gradle dependencies` to confirm the dependency resolves.
-
-## Step 4: Configure Authentication
-
-### 4a: Application Properties
-
-Add WorkOS configuration to `src/main/resources/application.properties`:
-
-```properties
-workos.api-key=${WORKOS_API_KEY}
-workos.client-id=${WORKOS_CLIENT_ID}
-workos.redirect-uri=http://localhost:8080/auth/callback
-```
-
-Or if the project uses `application.yml`, add the equivalent YAML.
-
-### 4b: Create WorkOS Configuration Bean
-
-Create a configuration class that initializes the WorkOS client:
-
-```kotlin
-@Configuration
-class WorkOSConfig {
-    @Value("\${workos.api-key}")
-    lateinit var apiKey: String
-
-    @Bean
-    fun workos(): WorkOS = WorkOS(apiKey)
-}
-```
-
-Adapt based on the SDK README — the exact client initialization may vary.
-
-### 4c: Create Auth Controller
-
-Create a Spring `@RestController` with these endpoints:
-
-1. **GET /auth/login** — Redirect user to WorkOS AuthKit hosted login
-   - Use `workos.userManagement.getAuthorizationUrl()` — this returns a URL string
-   - Parameters: `clientId`, `redirectUri`, `provider = "authkit"`
-   - The method uses a builder pattern: `.provider("authkit").redirectUri(uri).build()`
-
-2. **GET /auth/callback** — Exchange authorization code for user profile
-   - Extract `code` query parameter
-   - Call `workos.userManagement.authenticateWithCode()` with the code and clientId
-   - Store user session (use Spring's `HttpSession`)
-   - Redirect to home page
-
-3. **GET /auth/logout** — Clear session and redirect
-   - Invalidate `HttpSession`
-   - Redirect to home page or WorkOS logout URL
-
-**Follow the README for exact API method names and parameters.**
-
-## Step 5: Session Management
-
-Use Spring's built-in `HttpSession` for session management:
-
-- Store user profile in session after callback
-- Check session in protected routes
-- Clear session on logout
-
-If Spring Security is already configured, integrate with the existing security filter chain rather than replacing it.
-
-## Step 6: Verification
-
-Run the build to verify everything compiles:
-
-```bash
-./gradlew build
-```
-
-**If build fails:**
-
-- Check dependency resolution: `./gradlew dependencies | grep workos`
-- Check for missing imports in the auth controller
-- Verify application.properties syntax
-- Gradle builds can be slow (30-60s) — be patient
-
-### Checklist
-
-- [ ] WorkOS SDK dependency in build.gradle.kts
-- [ ] Application properties configured
-- [ ] Auth controller with login, callback, logout endpoints
-- [ ] Build succeeds (`./gradlew build`)
-
-## Error Recovery
-
-### Dependency resolution failure
-
-- Check Maven Central is accessible
-- Verify the artifact coordinates match README exactly
-- Ensure `mavenCentral()` is in the `repositories` block of build.gradle.kts
-
-### "Could not resolve com.workos:workos-kotlin"
-
-- The package may use a different group ID — check README
-- Ensure repositories block includes `mavenCentral()`
-
-### Build fails with missing Spring Boot annotations
-
-- Verify `org.springframework.boot` plugin is applied
-- Check Spring Boot starter dependencies are present
-
-### Gradle wrapper permission denied
-
-- Run `chmod +x ./gradlew` before building