workos 0.9.0 → 0.10.1

package/skills/workos-php-laravel/SKILL.md

@@ -1,182 +0,0 @@
----
-name: workos-php-laravel
-description: Integrate WorkOS AuthKit with Laravel applications. Uses the dedicated workos-php-laravel SDK with service provider, middleware, and config publishing.
----
-
-# WorkOS AuthKit for Laravel
-
-## Step 1: Fetch SDK Documentation (BLOCKING)
-
-**STOP. Do not proceed until complete.**
-
-WebFetch: `https://raw.githubusercontent.com/workos/workos-php-laravel/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 `artisan` file exists at project root
-- Confirm `composer.json` contains `laravel/framework` dependency
-- Confirm `app/` and `routes/` directories exist
-
-### 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:8000/auth/callback`)
-
-If `.env` exists but is missing these variables, append them. If `.env` doesn't exist, copy `.env.example` and add them.
-
-## Step 2b: Partial Install Recovery
-
-Before creating new files, check if a previous AuthKit attempt exists:
-
-1. Check if `workos/workos-php-laravel` is already in `composer.json`
-2. Check if `config/workos.php` exists but no auth controller or routes are wired
-3. If partial install detected:
-   - Do NOT reinstall the SDK (it's already there)
-   - Do NOT re-publish config if `config/workos.php` already exists
-   - Read existing files to understand what's done vs missing
-   - Complete the integration by filling gaps (controller, routes, middleware)
-   - Preserve any working code — only fix what's broken
-   - Check for missing auth controller or routes (most common gap)
-
-## Step 2c: Existing Auth System Detection
-
-Check for existing authentication before integrating:
-
-```
-composer.json has 'laravel/breeze'?               → Breeze auth scaffolding
-composer.json has 'laravel/jetstream'?            → Jetstream auth
-composer.json has 'laravel/fortify'?              → Fortify auth backend
-app/Http/Controllers/Auth/ exists?                → Auth controllers present
-routes/auth.php exists?                           → Auth routes file
-```
-
-If existing auth detected:
-
-- Do NOT remove or disable it
-- Add WorkOS AuthKit alongside the existing system
-- If Laravel session is already configured, reuse it for WorkOS
-- 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
-
-```bash
-composer require workos/workos-php-laravel
-```
-
-**Verify:** Check `composer.json` contains `workos/workos-php-laravel` in require section before continuing.
-
-## Step 4: Publish Configuration
-
-```bash
-php artisan vendor:publish --provider="WorkOS\Laravel\WorkOSServiceProvider"
-```
-
-This creates `config/workos.php`. Verify the file exists after publishing.
-
-If the artisan command fails, check README for the correct provider class name — it may differ.
-
-## Step 5: Configure Environment
-
-Ensure `.env` contains:
-
-```
-WORKOS_API_KEY=sk_...
-WORKOS_CLIENT_ID=client_...
-WORKOS_REDIRECT_URI=http://localhost:8000/auth/callback
-```
-
-Also ensure `config/workos.php` reads these env vars correctly. Check README for exact config structure.
-
-## Step 6: Create Auth Controller
-
-Create `app/Http/Controllers/AuthController.php` with methods for:
-
-- `login()` — Redirect to WorkOS AuthKit authorization URL
-- `callback()` — Handle OAuth callback, exchange code for user profile
-- `logout()` — Clear session and redirect
-
-Use SDK methods from README. Do NOT construct OAuth URLs manually.
-
-## Step 7: Add Routes
-
-Add to `routes/web.php`:
-
-```php
-use App\Http\Controllers\AuthController;
-
-Route::get('/login', [AuthController::class, 'login'])->name('login');
-Route::get('/auth/callback', [AuthController::class, 'callback']);
-Route::get('/logout', [AuthController::class, 'logout'])->name('logout');
-```
-
-Ensure the callback route path matches `WORKOS_REDIRECT_URI`.
-
-## Step 8: Add Middleware (if applicable)
-
-Check README for any authentication middleware the SDK provides. If available:
-
-1. Register middleware in `app/Http/Kernel.php` or `bootstrap/app.php` (Laravel 11+)
-2. Apply to routes that require authentication
-
-For Laravel 11+, middleware is registered in `bootstrap/app.php` instead of `Kernel.php`.
-
-## Step 9: Add UI Integration
-
-Update the home page or dashboard view to show:
-
-- Sign in link when user is not authenticated
-- User info and sign out link when authenticated
-
-Use Blade directives or SDK helpers from README.
-
-## Verification Checklist (ALL MUST PASS)
-
-```bash
-# 1. Config file exists
-ls config/workos.php
-
-# 2. Controller exists
-ls app/Http/Controllers/AuthController.php
-
-# 3. Routes registered
-php artisan route:list | grep -E "login|callback|logout"
-
-# 4. SDK installed
-composer show workos/workos-php-laravel
-
-# 5. Lint check
-php -l app/Http/Controllers/AuthController.php
-```
-
-## Error Recovery
-
-### "Class WorkOS\Laravel\WorkOSServiceProvider not found"
-
-- Verify `composer require` completed successfully
-- Run `composer dump-autoload`
-- Check `vendor/workos/` directory exists
-
-### "Route not defined"
-
-- Verify routes are in `routes/web.php`
-- Run `php artisan route:clear && php artisan route:cache`
-
-### Config not loading
-
-- Verify `config/workos.php` exists
-- Run `php artisan config:clear`
-- Check `.env` variables match config keys
-
-### Middleware issues (Laravel 11+)
-
-- Laravel 11 removed `Kernel.php` — register middleware in `bootstrap/app.php`
-- Check README for Laravel version-specific instructions

package/skills/workos-python/SKILL.md

@@ -1,193 +0,0 @@
----
-name: workos-python
-description: Integrate WorkOS AuthKit with Python applications. Adapts to Django, Flask, FastAPI, or vanilla Python. Server-side authentication with redirect-based OAuth flow.
----
-
-# WorkOS AuthKit for Python
-
-## Step 1: Fetch SDK Documentation (BLOCKING)
-
-**STOP. Do not proceed until complete.**
-
-WebFetch: `https://raw.githubusercontent.com/workos/workos-python/main/README.md`
-
-Also fetch the AuthKit quickstart for reference:
-WebFetch: `https://workos.com/docs/authkit/vanilla/python`
-
-The README is the source of truth for SDK API usage. If this skill conflicts with README, follow README.
-
-## Step 2: Detect Framework
-
-Examine the project to determine which Python web framework is in use:
-
-```
-manage.py exists?                        → Django
-  settings.py has django imports?        → Confirmed Django
-
-Gemfile/requirements has 'fastapi'?      → FastAPI
-  main.py has FastAPI() instance?        → Confirmed FastAPI
-
-requirements has 'flask'?               → Flask
-  server.py/app.py has Flask() instance? → Confirmed Flask
-
-None of the above?                       → Vanilla Python (use Flask quickstart pattern)
-```
-
-**Adapt all subsequent steps to the detected framework.** Do not force one framework onto another.
-
-## Step 2b: Partial Install Recovery
-
-Before creating new files, check if a previous AuthKit attempt exists:
-
-1. Check if `workos` is already in `requirements.txt` or `pyproject.toml`
-2. Check for incomplete auth files — files that import `workos` but have non-functional routes (TODO comments, commented-out code, empty handlers)
-3. If partial install detected:
-   - Do NOT reinstall the SDK (it's 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
-   - Check for a missing `/callback` route (most common gap)
-
-## Step 2c: Existing Auth System Detection
-
-Check for existing authentication before integrating:
-
-```
-requirements.txt has 'flask-login'?         → Flask-Login auth
-requirements.txt has 'authlib'?             → OAuth/OIDC auth (e.g., Auth0)
-requirements.txt has 'django-allauth'?      → Django allauth
-manage.py exists + 'django.contrib.auth'?   → Django built-in auth
-*.py files have 'flask_login'?              → Flask-Login in use
-```
-
-If existing auth detected:
-
-- Do NOT remove or disable it
-- Add WorkOS AuthKit alongside the existing system
-- If `flask-login` is present, use Flask-Login's session infrastructure (`login_user()`) for WorkOS auth too, rather than raw session management
-- 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: Pre-Flight Validation
-
-### Package Manager Detection
-
-```
-uv.lock exists?                          → uv add
-pyproject.toml has [tool.poetry]?        → poetry add
-Pipfile exists?                          → pipenv install
-requirements.txt exists?                 → pip install (+ append to requirements.txt)
-else                                     → pip install
-```
-
-### Environment Variables
-
-Check `.env` for:
-
-- `WORKOS_API_KEY` - starts with `sk_`
-- `WORKOS_CLIENT_ID` - starts with `client_`
-
-## Step 4: Install SDK
-
-Install using the detected package manager:
-
-```bash
-# uv
-uv add workos python-dotenv
-
-# poetry
-poetry add workos python-dotenv
-
-# pip
-pip install workos python-dotenv
-```
-
-If using `requirements.txt`, also append `workos` and `python-dotenv` to it.
-
-**Verify:** `python -c "import workos; print('OK')"`
-
-## Step 5: Integrate Authentication
-
-### If Django
-
-1. **Configure settings.py** — add `import os` + `from dotenv import load_dotenv` + `load_dotenv()` at top. Add `WORKOS_API_KEY` and `WORKOS_CLIENT_ID` from `os.environ.get()`.
-2. **Create auth views** — create `auth_views.py` (or add to existing views):
-   - `login_view`: call SDK's `get_authorization_url()` with `provider='authkit'`, redirect
-   - `callback_view`: call `authenticate_with_code()` with the code param, store user in `request.session`
-   - `logout_view`: flush session, redirect
-3. **Add URL patterns** — add `auth/login/`, `auth/callback/`, `auth/logout/` to `urls.py`
-4. **Update templates** — add login/logout links using `{% url %}` tags
-
-### If Flask
-
-Follow the quickstart pattern exactly:
-
-1. **Initialize WorkOS client** in `server.py` / `app.py`:
-   ```python
-   from workos import WorkOSClient
-   workos = WorkOSClient(api_key=os.getenv("WORKOS_API_KEY"), client_id=os.getenv("WORKOS_CLIENT_ID"))
-   ```
-2. **Create `/login` route** — call `workos.user_management.get_authorization_url(provider="authkit", redirect_uri="...")`, redirect
-3. **Create `/callback` route** — call `workos.user_management.authenticate_with_code(code=code)`, set session cookie
-4. **Create `/logout` route** — clear session, redirect
-5. **Update home route** — show user info if session exists
-
-### If FastAPI
-
-1. **Initialize WorkOS client** in main app file
-2. **Create `/login` endpoint** — generate auth URL, return `RedirectResponse`
-3. **Create `/callback` endpoint** — exchange code, store in session/cookie
-4. **Create `/logout` endpoint** — clear session
-5. Use `Depends()` for auth middleware on protected routes
-
-### If Vanilla Python (no framework detected)
-
-Install Flask and follow the Flask pattern above. This matches the official quickstart.
-
-## Step 6: Environment Setup
-
-Create/update `.env` with WorkOS credentials. Do NOT overwrite existing values.
-
-```
-WORKOS_API_KEY=sk_...
-WORKOS_CLIENT_ID=client_...
-```
-
-## Step 7: Verification Checklist
-
-```bash
-# 1. SDK importable
-python -c "import workos; print('OK')"
-
-# 2. Credentials configured
-python -c "
-from dotenv import load_dotenv; import os; load_dotenv()
-assert os.environ.get('WORKOS_API_KEY','').startswith('sk_'), 'Missing WORKOS_API_KEY'
-assert os.environ.get('WORKOS_CLIENT_ID','').startswith('client_'), 'Missing WORKOS_CLIENT_ID'
-print('Credentials OK')
-"
-
-# 3. Framework-specific check
-# Django: python manage.py check
-# Flask: python -m py_compile server.py
-# FastAPI: python -m py_compile main.py
-```
-
-## Error Recovery
-
-### "ModuleNotFoundError: No module named 'workos'"
-
-Re-run the install command for the detected package manager.
-
-### Django: "CSRF verification failed"
-
-Auth callback receives GET requests from WorkOS. Ensure callback view uses GET, not POST. Or add `@csrf_exempt`.
-
-### Flask: Session not persisting
-
-Ensure `app.secret_key` is set (required for Flask sessions).
-
-### Virtual environment not active
-
-Check for `.venv/`, `venv/`, or poetry-managed environments. Activate before running install.

package/skills/workos-ruby/SKILL.md

@@ -1,198 +0,0 @@
----
-name: workos-ruby
-description: Integrate WorkOS AuthKit with Ruby applications. Adapts to Rails, Sinatra, or vanilla Ruby. Server-side authentication with redirect-based OAuth flow.
----
-
-# WorkOS AuthKit for Ruby
-
-## Step 1: Fetch SDK Documentation (BLOCKING)
-
-**STOP — Do not proceed until this fetch is complete.**
-
-WebFetch: `https://raw.githubusercontent.com/workos/workos-ruby/main/README.md`
-
-Also fetch the AuthKit quickstart for reference:
-WebFetch: `https://workos.com/docs/authkit/vanilla/ruby`
-
-The README is the **source of truth** for gem API usage. If this skill conflicts with the README, **follow the README**.
-
-## Step 2: Detect Framework
-
-Examine the project to determine which Ruby web framework is in use:
-
-```
-config/routes.rb exists?                 → Rails
-  Gemfile has 'rails' gem?               → Confirmed Rails
-
-Gemfile has 'sinatra' gem?               → Sinatra
-  server.rb/app.rb has Sinatra routes?   → Confirmed Sinatra
-
-None of the above?                       → Vanilla Ruby (use Sinatra quickstart pattern)
-```
-
-**Adapt all subsequent steps to the detected framework.** Do not force Rails on a Sinatra project or vice versa.
-
-## Step 2b: Partial Install Recovery
-
-Before creating new files, check if a previous AuthKit attempt exists:
-
-1. Check if `workos` is already in `Gemfile`
-2. Check for incomplete auth files — files that `require "workos"` but have non-functional routes (TODO comments, 501 responses, empty handlers)
-3. If partial install detected:
-   - Do NOT reinstall the gem (it's 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
-   - Run `bundle install` (not `bundle update`) to avoid unexpected gem upgrades
-
-## Step 2c: Existing Auth System Detection
-
-Check for existing authentication before integrating:
-
-```
-Gemfile has 'devise'?                       → Devise auth (uses Warden)
-Gemfile has 'warden'?                       → Warden auth
-Gemfile has 'omniauth'?                     → OmniAuth (OAuth/OIDC)
-*.rb files have 'Warden'?                   → Warden middleware in use
-config/initializers has devise.rb?          → Devise configured
-```
-
-If existing auth detected:
-
-- Do NOT remove or disable it
-- Add WorkOS AuthKit alongside the existing system
-- If Devise is present, Devise uses Warden under the hood — integrate WorkOS at the Warden strategy level if possible
-- Create separate route paths for WorkOS auth (e.g., `/auth/workos/login` if `/login` is taken)
-- Ensure Rack middleware ordering is correct (WorkOS session middleware must not conflict)
-- Ensure existing auth routes continue to work unchanged
-- Document in code comments how to migrate fully to WorkOS later
-
-## Step 3: Install WorkOS Gem
-
-```bash
-bundle add workos
-```
-
-If `dotenv` is not in the Gemfile:
-
-```bash
-# Rails
-bundle add dotenv-rails --group development,test
-
-# Sinatra / other
-bundle add dotenv
-```
-
-**Verify:** `bundle show workos`
-
-## Step 4: Integrate Authentication
-
-### If Rails
-
-1. **Create initializer** — `config/initializers/workos.rb`:
-
-   ```ruby
-   WorkOS.configure do |config|
-     config.api_key = ENV.fetch("WORKOS_API_KEY")
-     config.client_id = ENV.fetch("WORKOS_CLIENT_ID")
-   end
-   ```
-
-2. **Create AuthController** — `app/controllers/auth_controller.rb`:
-   - `login` action: call `WorkOS::UserManagement.get_authorization_url(provider: "authkit", redirect_uri: ...)`, redirect
-   - `callback` action: call `WorkOS::UserManagement.authenticate_with_code(code: params[:code])`, store user in session
-   - `logout` action: clear session, redirect
-
-3. **Add routes** to `config/routes.rb`:
-
-   ```ruby
-   get "/auth/login", to: "auth#login"
-   get "/auth/callback", to: "auth#callback"
-   get "/auth/logout", to: "auth#logout"
-   ```
-
-4. **Add current_user helper** to `ApplicationController` (optional):
-
-   ```ruby
-   helper_method :current_user
-   def current_user
-     @current_user ||= session[:user] && JSON.parse(session[:user])
-   end
-   ```
-
-5. **Verify:** `bundle exec rails routes | grep auth`
-
-### If Sinatra
-
-Follow the quickstart pattern exactly:
-
-1. **Configure WorkOS** in `server.rb`:
-
-   ```ruby
-   require "dotenv/load"
-   require "workos"
-   require "sinatra"
-
-   WorkOS.configure do |config|
-     config.key = ENV["WORKOS_API_KEY"]
-   end
-   ```
-
-2. **Create `/login` route** — call `WorkOS::UserManagement.authorization_url(provider: "authkit", client_id: ..., redirect_uri: ...)`, redirect
-
-3. **Create `/callback` route** — call `WorkOS::UserManagement.authenticate_with_code(client_id: ..., code: ...)`, store in session cookie
-
-4. **Create `/logout` route** — clear session cookie, redirect
-
-5. **Update home route** — read session, show user info if present
-
-6. **Verify:** `ruby -c server.rb`
-
-### If Vanilla Ruby (no framework detected)
-
-Install Sinatra and follow the Sinatra pattern above. This matches the official quickstart.
-
-## Step 5: Environment Setup
-
-Create/update `.env` with WorkOS credentials. Do NOT overwrite existing values.
-
-```
-WORKOS_API_KEY=sk_...
-WORKOS_CLIENT_ID=client_...
-```
-
-## Step 6: Verification
-
-### Rails
-
-```bash
-bundle show workos
-bundle exec rails routes | grep auth
-grep WORKOS .env
-```
-
-### Sinatra
-
-```bash
-bundle show workos
-ruby -c server.rb
-grep WORKOS .env
-```
-
-## Error Recovery
-
-### "uninitialized constant WorkOS"
-
-Gem not loaded. Verify `bundle show workos` succeeds. For Rails, ensure initializer exists. For Sinatra, ensure `require "workos"` is at top of server file.
-
-### "NoMethodError" on WorkOS methods
-
-SDK API may differ from this skill. Re-read the README (Step 1) and use exact method names.
-
-### Routes not working (Rails)
-
-Run `bundle exec rails routes | grep auth`. Verify routes are inside `Rails.application.routes.draw` block.
-
-### Session not persisting (Sinatra)
-
-Enable sessions: `enable :sessions` in server.rb, or use `rack-session` gem.