@netlify/agent-runner-cli 1.88.0-alpha.1 → 1.88.0

package/dist/skills/netlify-identity/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: netlify-identity
-description: Add user authentication with Netlify Identity. Use when implementing signups, logins, password recovery, role-based access control, OAuth providers, or protecting Netlify Functions with user tokens.
+description: Add user authentication with Netlify Identity. Use when implementing signups, logins, password recovery, role-based access control, OAuth providers, protecting Netlify Functions, or server-side auth in SSR frameworks.
 ---
 
 # Netlify Identity
@@ -8,190 +8,139 @@ description: Add user authentication with Netlify Identity. Use when implementin
 Netlify Identity is a user management service for signups, logins, password recovery, user metadata, and role-based
 access control. It is built on [GoTrue](https://github.com/netlify/gotrue) and issues JSON Web Tokens (JWTs).
 
-There are two integration paths:
+`@netlify/identity` is the recommended library for integrating with Netlify Identity. It provides a unified, headless
+API that works in both browser and server contexts (Netlify Functions, Edge Functions, SSR frameworks). You do not need
+`gotrue-js` or `netlify-identity-widget` separately.
 
-- **Widget** (`netlify-identity-widget`) — Drop-in UI modal for login, signup, and password recovery. Zero framework
-  dependencies. Best when you want auth working quickly without building custom forms.
-- **gotrue-js** — Programmatic client for full control over authentication flows. Best when you need custom UI or
-  headless auth logic.
+- **`@netlify/identity`** — Default choice. Headless TypeScript API for browser and server. Full control over auth UI.
+  Works with SSR frameworks (Next.js, Remix, Astro, SvelteKit, TanStack Start).
+- **`netlify-identity-widget`** — Browser-only drop-in UI modal for login, signup, and password recovery. Zero custom
+  code needed. **Does not work server-side** — no SSR, no Netlify Functions, no Edge Functions. Use only when the user
+  wants a pre-built auth modal with no custom design.
 
-Both communicate with the Identity endpoint at `/.netlify/identity` on your site.
-
-## Quick Start
-
-Add the widget CDN script and a menu element for instant auth:
-
-```html
-<script type="text/javascript" src="https://identity.netlify.com/v1/netlify-identity-widget.js"></script>
-<div data-netlify-identity-menu></div>
-```
-
-Handle logins:
+## Setup
 
-```javascript
-netlifyIdentity.on('login', async (user) => {
-  const jwt = await netlifyIdentity.refresh()
-  await fetch('/.netlify/functions/protected', {
-    headers: { Authorization: `Bearer ${jwt}` },
-  })
-})
+```bash
+npm install @netlify/identity
 ```
 
-### When to Use Widget vs gotrue-js
-
-- **Prefer the widget** when the user wants auth working quickly, doesn't have custom UI requirements, or is building a
-  simple site. It requires minimal code and automatically sets the `nf_jwt` cookie needed for role-based redirects.
-- **Use gotrue-js** when the user needs custom login/signup forms, headless auth, or programmatic control over the auth
-  flow. Pass `setCookie: true` if you need role-based redirects (see below).
-- **Never mix both** in the same page unless accessing `netlifyIdentity.gotrue` for low-level operations while using the
-  widget for UI.
-
-## Setup
-
 Identity is automatically enabled when the deploy includes Identity code. Default settings:
 
 - **Registration** — Open (anyone can sign up). Change to Invite only in **Project configuration > Identity** if needed.
-- **Autoconfirm** — Off (new signups require email confirmation). Enable in **Project configuration > Identity** to skip confirmation during development.
+- **Autoconfirm** — Off (new signups require email confirmation). Enable in **Project configuration > Identity** to skip
+  confirmation during development.
 
-## Widget (Drop-in UI)
+For local development, use `netlify dev` so the Identity endpoint is available.
 
-### CDN Script Tag
+## Quick Start
 
-Include the widget script and add HTML attributes for automatic controls:
+Log in from the browser:
 
-```html
-<script type="text/javascript" src="https://identity.netlify.com/v1/netlify-identity-widget.js"></script>
+```typescript
+import { login, getUser } from '@netlify/identity'
 
-<!-- Login/Signup menu (shows username + logout when logged in) -->
-<div data-netlify-identity-menu></div>
+const user = await login('jane@example.com', 'password123')
+console.log(`Hello, ${user.name}`)
 
-<!-- Simple button that opens the modal -->
-<div data-netlify-identity-button>Login with Netlify Identity</div>
+// Later, check auth state
+const currentUser = await getUser()
 ```
 
-The widget attaches itself to `window.netlifyIdentity` automatically.
-
-### npm Module
-
-```bash
-npm install netlify-identity-widget
-```
+Protect a Netlify Function:
 
-```javascript
-import netlifyIdentity from 'netlify-identity-widget'
-
-netlifyIdentity.init({
-  container: '#netlify-modal', // defaults to document.body
-  locale: 'en',               // language code (en, fr, es, pt, de, etc.)
-  // APIUrl: 'https://your-site.netlify.app/.netlify/identity', // only for non-Netlify hosts
-})
+```typescript
+// netlify/functions/protected.mts
+import { getUser } from '@netlify/identity'
+import type { Context } from '@netlify/functions'
+
+export default async (req: Request, context: Context) => {
+  const user = await getUser()
+  if (!user) return new Response('Unauthorized', { status: 401 })
+  return Response.json({ id: user.id, email: user.email })
+}
 ```
 
-Set `APIUrl` only when the app is served from a different domain than the Identity endpoint (Cordova, Electron, or
-custom domains).
+ALWAYS use `@netlify/identity` for new Identity integrations. ONLY use `netlify-identity-widget` if the user explicitly
+asks for a drop-in UI modal. ALWAYS use TypeScript (`.mts`) for functions that use Identity.
 
-### Events
+## Full API Reference
 
-```javascript
-netlifyIdentity.on('init', (user) => console.log('init', user))
-netlifyIdentity.on('login', (user) => console.log('login', user))
-netlifyIdentity.on('logout', () => console.log('Logged out'))
-netlifyIdentity.on('error', (err) => console.error('Error', err))
+For the complete API reference — all function signatures, type definitions, OAuth helpers, admin operations, session
+management, auth events, and framework-specific integration examples — read the package README:
 
-netlifyIdentity.off('login')           // unbind all login handlers
-netlifyIdentity.off('login', handler)  // unbind a specific handler
 ```
-
-### Key Methods
-
-```javascript
-netlifyIdentity.open()                                // open modal (default tab)
-netlifyIdentity.open('login')                         // open to login tab
-netlifyIdentity.open('signup')                        // open to signup tab
-netlifyIdentity.open('signup', { full_name: 'Jane' }) // pre-fill signup metadata
-netlifyIdentity.close()
-netlifyIdentity.logout()
-const user = netlifyIdentity.currentUser()            // null if not logged in
-const jwt = await netlifyIdentity.refresh()           // refresh the JWT
-const gotrueClient = netlifyIdentity.gotrue           // underlying GoTrue client
+node_modules/@netlify/identity/README.md
 ```
 
-## gotrue-js (Programmatic Client)
+The README is shipped with the npm package and is always in sync with the installed version.
 
-### Install
+## SSR Integration Patterns
 
-```bash
-npm install gotrue-js
-```
+For SSR frameworks, the recommended pattern is:
 
-### Initialize
+- **Browser-side** for auth mutations: `login()`, `signup()`, `logout()`, `oauthLogin()`
+- **Server-side** for reading auth state: `getUser()`, `getSettings()`, `getIdentityConfig()`
 
-```typescript
-import GoTrue from 'gotrue-js'
+Browser-side auth mutations set the `nf_jwt` cookie and localStorage, and emit `onAuthChange` events. The
+server reads the cookie on the next request.
 
-const auth = new GoTrue({
-  APIUrl: 'https://<your-site>.netlify.app/.netlify/identity',
-  setCookie: false,
-})
-```
+The library also supports server-side mutations (`login()`, `signup()`, `logout()` inside Netlify Functions), but these
+require the Netlify Functions runtime to set cookies. After a server-side mutation, use a full page navigation so the
+browser sends the new cookie.
 
-`setCookie: true` tells the server to set HttpOnly cookies, which protects tokens from XSS but is required if you need
-role-based redirects without the widget (the CDN reads an `nf_jwt` cookie to evaluate redirect conditions). Use `false`
-when you manage tokens entirely in JavaScript and don't need CDN-level access control.
+ALWAYS use `window.location.href` (not framework router navigation) after server-side auth mutations in Next.js,
+TanStack Start, and SvelteKit. Remix `redirect()` is safe because Remix actions return real HTTP responses.
 
-### Core Methods
+## Identity Event Functions
 
-```javascript
-// Signup (sends confirmation email if autoconfirm is off)
-const response = await auth.signup(email, password)
-// Pass user_metadata during signup: auth.signup(email, password, { full_name: 'Jane' })
+Special serverless functions that trigger on Identity lifecycle events. These use the **legacy named `handler` export**
+(not the modern default export) because they receive `event.body` containing the user payload.
 
-// Confirm email (token from confirmation email URL fragment)
-const user = await auth.confirm(token, true)        // remember = persist session
+ALWAYS use the legacy named `handler` export (not default export) for Identity event functions. The filename MUST match
+the event name exactly (e.g., `netlify/functions/identity-signup.mts`).
 
-// Login
-const user = await auth.login(email, password, true) // remember = persist session
+**Event names:** `identity-validate`, `identity-signup`, `identity-login`
 
-// Current user (from localStorage)
-const user = auth.currentUser()
+- `identity-signup` — fires when a new user signs up (email/password or OAuth)
+- `identity-login` — fires on each login
+- `identity-validate` — fires during signup before the user is created; return a non-200 status to reject
 
-// Get fresh JWT (auto-refreshes if expired; pass true to force)
-const token = await user.jwt()
+### Example: Assign Default Role on Signup
 
-// Update user
-await user.update({ email: 'new@example.com', password: 'newpassword' })
-await user.update({ data: { full_name: 'Jane Doe' } }) // update user_metadata
+```typescript
+// netlify/functions/identity-signup.mts
+import type { Handler, HandlerEvent, HandlerContext } from '@netlify/functions'
 
-// Logout
-await user.logout()
+const handler: Handler = async (event: HandlerEvent, context: HandlerContext) => {
+  const { user } = JSON.parse(event.body || '{}')
 
-// Password recovery
-await auth.requestPasswordRecovery(email)               // sends recovery email
-const user = await auth.recover(recoveryToken, true)    // remember = persist session
+  return {
+    statusCode: 200,
+    body: JSON.stringify({
+      app_metadata: {
+        ...user.app_metadata,
+        roles: ['member'],
+      },
+    }),
+  }
+}
 
-// Check server settings (signup enabled? autoconfirm? OAuth providers?)
-const settings = await auth.settings()
+export { handler }
 ```
 
-### Error Handling
-
-gotrue-js exports `JSONHTTPError`, `TextHTTPError`, and `HTTPError` for granular error catching. Use `error.json`,
-`error.data`, or `error.status` respectively.
-
-## Token Handling
+The response body replaces `app_metadata` and/or `user_metadata` on the user record — include all fields you want to
+keep, not just new ones.
 
-- Access tokens expire after **1 hour**
-- Both `user.jwt()` (gotrue-js) and `netlifyIdentity.refresh()` (widget) auto-refresh using the refresh token
-- Always call `jwt()` or `refresh()` before authenticated requests — do not cache tokens
-- Send the token as `Authorization: Bearer <token>`
+For bulk user management or role changes outside lifecycle events, use the `admin` API instead of Identity event
+functions.
 
 ## Roles and Authorization
 
 ### Metadata Types
 
-- **`app_metadata.roles`** — Server-controlled. Only settable via the Netlify UI, admin API, or server-side code
-  (Identity event functions, protected functions with admin token). Do not allow users to set their own roles.
-- **`user_metadata`** — User-controlled. Users can update this via `user.update({ data: { ... } })`.
+- **`app_metadata.roles`** — Server-controlled. Only settable via the Netlify UI, admin API, or Identity event functions.
+  Do not allow users to set their own roles.
+- **`user_metadata`** — User-controlled. Users can update this via `updateUser({ data: { ... } })`.
 
 ### Role-Based Redirects
 
@@ -213,117 +162,72 @@ Use `netlify.toml` to restrict paths by role:
 Rules are evaluated top-to-bottom. The first redirect matches users with the `admin` role; everyone else falls through
 to the second rule and is redirected away.
 
-**How it works:** The widget sets an `nf_jwt` cookie that the CDN reads to evaluate `conditions = { Role = [...] }`.
-Without this cookie, role-based redirects will not work. If using gotrue-js instead of the widget, pass
-`setCookie: true` when initializing GoTrue so the server sets this cookie.
+**How it works:** The `nf_jwt` cookie is read by the CDN to evaluate `conditions = { Role = [...] }`. Without this
+cookie, role-based redirects will not work.
 
-## Identity Event Functions
+## Common Errors & Solutions
 
-Special serverless functions that trigger on Identity lifecycle events. These use the **legacy named `handler` export**
-(not the modern default export) because they receive `event.body` containing the user payload.
+### "Signups not allowed for this instance" (403)
 
-**Event names:** `identity-validate`, `identity-signup`, `identity-login`
+**Cause:** Registration is set to Invite only.
 
-- `identity-signup` — fires when a new user signs up (email/password or OAuth)
-- `identity-login` — fires on each login
-- `identity-validate` — fires during signup before the user is created; return a non-200 status to reject the signup
+**Fix:**
 
-The filename must match the event name exactly (e.g. `netlify/functions/identity-signup.mts`).
+1. Change to Open in **Project configuration > Identity**
+2. Or invite users from the Identity tab in the Netlify UI
 
-### Example: Assign Default Role on Signup
+### "Token expired" / 401 on API calls
 
-```typescript
-// netlify/functions/identity-signup.mts
-import type { Handler, HandlerEvent, HandlerContext } from '@netlify/functions'
+**Cause:** Stale access token.
 
-const handler: Handler = async (event: HandlerEvent, context: HandlerContext) => {
-  const { user } = JSON.parse(event.body || '{}')
+**Fix:**
 
-  return {
-    statusCode: 200,
-    body: JSON.stringify({
-      app_metadata: {
-        ...user.app_metadata,
-        roles: ['member'],
-      },
-    }),
-  }
-}
+1. Always use `getUser()` before authenticated requests
+2. In the browser, the library auto-refreshes tokens
+3. On the server, call `refreshSession()` in middleware to handle near-expiry tokens
 
-export { handler }
-```
+### Identity event function not triggering
 
-The response body replaces `app_metadata` and/or `user_metadata` on the user record — include all fields you want to
-keep, not just new ones.
+**Cause:** Filename or export format does not match expected convention.
 
-## Protected Functions
+**Fix:**
 
-Functions that verify the calling user's identity. Use the legacy `handler` export to access `context.clientContext`.
+1. Verify filename matches exactly: `identity-signup`, `identity-validate`, or `identity-login`
+2. Place in `netlify/functions/` with `.mts` or `.mjs` extension
+3. Use named `handler` export (not default export)
 
-```typescript
-// netlify/functions/protected-action.mts
-import type { Handler, HandlerEvent, HandlerContext } from '@netlify/functions'
+### `MissingIdentityError`
 
-const handler: Handler = async (event: HandlerEvent, context: HandlerContext) => {
-  const { identity, user } = context.clientContext || {}
+**Cause:** Identity is not configured in the current environment.
 
-  if (!user) {
-    return { statusCode: 401, body: JSON.stringify({ error: 'Unauthorized' }) }
-  }
+**Fix:**
 
-  // user.sub — user ID
-  // user.email — email address
-  // user.app_metadata.roles — assigned roles
-  // user.user_metadata — user-controlled data
-
-  // Use identity.token (admin token) to call the Identity admin API:
-  const adminAuthHeader = `Bearer ${identity.token}`
-  const response = await fetch(`${identity.url}/admin/users/${user.sub}`, {
-    method: 'PUT',
-    headers: { Authorization: adminAuthHeader },
-    body: JSON.stringify({ app_metadata: { roles: ['editor'] } }),
-  })
-
-  const data = await response.json()
-  return { statusCode: 200, body: JSON.stringify(data) }
-}
+1. Ensure Identity is enabled on the project
+2. Use `netlify dev` for local development so the Identity endpoint is available
 
-export { handler }
-```
+### `AuthError` on server — missing Netlify runtime
 
-**Note:** Operations using `identity.token` (admin token) do **not** work locally with `netlify dev`. Deploy to Netlify
-to test server-side admin operations.
+**Cause:** Server-side `login()`, `signup()`, or `logout()` require the Netlify Functions runtime to set cookies.
 
-## External OAuth Providers
+**Fix:**
 
-Netlify Identity supports Google, GitHub, GitLab, and BitBucket as built-in OAuth providers.
+1. Deploy to Netlify to use server-side auth mutations
+2. Or use `netlify dev` for local development
 
-**Enable in Netlify UI:** Project configuration > Identity > Registration > External providers
+### "User not found" after OAuth login
 
-### Widget
+**Cause:** OAuth provider is not enabled for the project.
 
-Once enabled in the UI, the widget automatically shows OAuth provider buttons. No additional code needed.
+**Fix:**
 
-### gotrue-js
+1. Enable the provider in **Project configuration > Identity > External providers**
+2. Users are created automatically on first OAuth login
 
-```javascript
-const url = auth.loginExternalUrl('github')
-// Redirect the user to this URL to start the OAuth flow
-window.location.href = url
-```
+### Account operations fail after server-side login
 
-Available provider names: `'google'`, `'github'`, `'gitlab'`, `'bitbucket'`
+**Cause:** Browser-side session is not bootstrapped from server-set cookies.
 
-## Common Errors & Solutions
+**Fix:**
 
-- **"Signups not allowed for this instance" (403)** — Registration is set to Invite only. Change to Open in Project
-  configuration > Identity, or invite users from the Identity tab.
-- **"Token expired" / 401 on API calls** — Stale access token. Always call `user.jwt()` or `netlifyIdentity.refresh()`
-  before authenticated requests.
-- **Identity event function not triggering** — Verify filename matches exactly (`identity-signup`, `identity-validate`,
-  or `identity-login`), is in `netlify/functions/`, and uses `.mts`/`.mjs`.
-- **`clientContext` is undefined** — Use named `handler` export (not `export default`), send `Authorization: Bearer`
-  header, and verify token is fresh.
-- **Admin methods not working locally** — `identity.token` is unavailable in local dev. Deploy to Netlify to test.
-- **"User not found" after OAuth login** — Enable the OAuth provider in Project configuration > Identity > External
-  providers. Users are created on first OAuth login.
+1. Call `hydrateSession()` on page load to bridge server-set cookies to the browser session
+2. Then use `updateUser()`, `verifyEmailChange()`, or other account operations

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@netlify/agent-runner-cli",
   "type": "module",
-  "version": "1.88.0-alpha.1",
+  "version": "1.88.0",
   "description": "CLI tool for running Netlify agents",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -42,6 +42,7 @@
     "test:integration:gemini": "vitest run test/integration/gemini.test.ts",
     "test:integration:create-stage": "vitest run test/integration/create.test.ts",
     "test:integration:skill-invocation": "vitest run test/integration/skill-invocation.test.ts",
+    "check:types": "tsc --noEmit",
     "postinstall": "node scripts/postinstall.js"
   },
   "config": {
@@ -82,7 +83,7 @@
     "@anthropic-ai/claude-code": "2.1.63",
     "@anthropic-ai/sdk": "0.78.0",
     "@google/gemini-cli": "0.31.0",
-    "@netlify/otel": "^5.1.1",
+    "@netlify/otel": "^5.1.2",
     "@openai/codex": "0.110.0",
     "@opentelemetry/exporter-trace-otlp-grpc": "^0.212.0",
     "execa": "^9.6.1",