workos 0.4.5 → 0.5.1

package/skills/workos-php/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: workos-php
+description: Integrate WorkOS AuthKit with generic PHP applications. Uses the workos-php SDK directly with standalone auth endpoint files.
+---
+
+# WorkOS AuthKit for PHP
+
+## Step 1: Fetch SDK Documentation (BLOCKING)
+
+**STOP. Do not proceed until complete.**
+
+WebFetch: `https://github.com/workos/workos-php/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 `composer.json` exists at project root
+- If `composer.json` doesn't exist, create a minimal one with `composer init --no-interaction`
+
+### Environment Variables
+
+Check for `.env` file with:
+
+- `WORKOS_API_KEY` - starts with `sk_`
+- `WORKOS_CLIENT_ID` - starts with `client_`
+- `WORKOS_REDIRECT_URI` - valid callback URL (e.g., `http://localhost:8000/callback.php`)
+
+If `.env` doesn't exist, create it with the required variables.
+
+## Step 3: Install SDK
+
+```bash
+composer require workos/workos-php
+```
+
+**Verify:** Check `composer.json` contains `workos/workos-php` in require section.
+
+Also install a dotenv library if not present:
+
+```bash
+composer require vlucas/phpdotenv
+```
+
+## Step 4: Create Bootstrap File
+
+Create a bootstrap or config file (e.g., `config.php` or `bootstrap.php`) that:
+
+1. Requires Composer autoloader: `require_once __DIR__ . '/vendor/autoload.php';`
+2. Loads `.env` using phpdotenv
+3. Initializes the WorkOS SDK client with API key
+
+Use SDK initialization from README. Do NOT hardcode credentials.
+
+## Step 5: Create Auth Endpoint Files
+
+### `login.php`
+
+- Initialize WorkOS client (include bootstrap)
+- Generate authorization URL using SDK
+- Redirect user to WorkOS AuthKit
+
+### `callback.php`
+
+- Initialize WorkOS client (include bootstrap)
+- Exchange authorization code from `$_GET['code']` for user profile using SDK
+- Start session, store user data
+- Redirect to home/dashboard
+
+### `logout.php`
+
+- Destroy session
+- Redirect to home page
+
+Use SDK methods from README for all WorkOS API calls. Do NOT construct OAuth URLs manually.
+
+## Step 6: Create Home Page
+
+Create or update `index.php` to show:
+
+- Sign in link (`login.php`) when no session
+- User info and sign out link (`logout.php`) when session exists
+
+## Verification Checklist (ALL MUST PASS)
+
+```bash
+# 1. SDK installed
+composer show workos/workos-php
+
+# 2. Auth files exist
+ls login.php callback.php logout.php
+
+# 3. No syntax errors
+php -l login.php
+php -l callback.php
+php -l logout.php
+php -l index.php
+
+# 4. Autoloader exists
+ls vendor/autoload.php
+```
+
+## Error Recovery
+
+### "Class WorkOS\WorkOS not found"
+
+- Verify `composer require` completed successfully
+- Check `vendor/autoload.php` is required in bootstrap
+- Run `composer dump-autoload`
+
+### Session issues
+
+- Ensure `session_start()` is called before any session access
+- Check PHP session configuration (`session.save_path`)
+
+### Redirect URI mismatch
+
+- Compare callback file path to `WORKOS_REDIRECT_URI` in `.env`
+- URLs must match exactly (including trailing slash)
+
+### Environment variables not loading
+
+- Verify `.env` file exists in project root
+- Verify phpdotenv is installed and loaded in bootstrap
+- Check file permissions on `.env`

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

@@ -0,0 +1,147 @@
+---
+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://github.com/workos/workos-php-laravel/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 `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 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

@@ -0,0 +1,159 @@
+---
+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 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

@@ -0,0 +1,163 @@
+---
+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 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.