@netlify/agent-runner-cli 2.16.0-server.1 → 2.16.0-server.3

package/dist/skills/netlify-identity/references/advanced-patterns.md

@@ -0,0 +1,104 @@
+# Advanced Identity Patterns
+
+## Password Recovery
+
+Three-step flow: request recovery email, handle the callback, then set a new password.
+
+```typescript
+import { requestPasswordRecovery, handleAuthCallback, updateUser, AuthError } from '@netlify/identity'
+
+// Step 1: Send recovery email
+async function handleForgotPassword(email: string) {
+  try {
+    await requestPasswordRecovery(email)
+    showSuccess('Check your email for a password reset link.')
+  } catch (error) {
+    if (error instanceof AuthError) showError(error.message)
+  }
+}
+
+// Step 2: handleAuthCallback() returns { type: 'recovery', user } — show password reset form
+// (See the handleAuthCallback switch in SKILL.md)
+
+// Step 3: Set new password
+async function handlePasswordReset(newPassword: string) {
+  try {
+    await updateUser({ password: newPassword })
+    showSuccess('Password updated.')
+  } catch (error) {
+    if (error instanceof AuthError) showError(error.message)
+  }
+}
+```
+
+The recovery callback fires a `'recovery'` auth event, not `'login'`. The user is authenticated but should be prompted to set a new password before navigating away.
+
+## Invite Acceptance
+
+When a user clicks an invite link, `handleAuthCallback()` returns `{ type: 'invite', user: null, token }`. Use the token to accept the invite and set a password.
+
+```typescript
+import { acceptInvite, AuthError } from '@netlify/identity'
+
+async function handleAcceptInvite(token: string, password: string) {
+  try {
+    const user = await acceptInvite(token, password)
+    showSuccess(`Welcome, ${user.email}! Your account is ready.`)
+  } catch (error) {
+    if (error instanceof AuthError) showError(error.message)
+  }
+}
+```
+
+## Email Change
+
+When a user verifies an email change, `handleAuthCallback()` returns `{ type: 'email_change', user }` with the change already applied — the returned `user` carries the new email. The user must be logged in when clicking the verification link.
+
+Like recovery (and unlike invite acceptance), there is no token to consume and no follow-up call — `handleAuthCallback()` does the work. Handle it in the `handleAuthCallback()` switch (see SKILL.md) and confirm the new address.
+
+```typescript
+// In the handleAuthCallback() switch (see SKILL.md):
+case 'email_change':
+  showSuccess(`Email updated to ${result.user?.email}`)
+  break
+```
+
+If you process the verification token yourself instead of letting `handleAuthCallback()` read the URL hash, call `verifyEmailChange(token)` directly — it applies the change and returns the updated user.
+
+## Session Hydration
+
+`hydrateSession()` bridges server-set cookies to the browser session. Call it on page load when using server-side login (e.g., login inside a Netlify Function followed by a redirect).
+
+```typescript
+import { hydrateSession } from '@netlify/identity'
+
+const user = await hydrateSession()
+if (user) {
+  // Browser session is now in sync with server-set cookies
+}
+```
+
+`getUser()` auto-hydrates from the `nf_jwt` cookie if no browser session exists, so explicit `hydrateSession()` is only needed when you want to restore the full session (including token refresh timers) after a server-side login.
+
+## SSR Integration Patterns
+
+For SSR frameworks, the recommended pattern is:
+
+- **Browser-side** for auth mutations: `login()`, `signup()`, `logout()`, `oauthLogin()`
+- **Server-side** for reading auth state: `getUser()`, `getSettings()`, `getIdentityConfig()`
+
+Browser-side auth mutations set the `nf_jwt` cookie and localStorage, and emit `onAuthChange` events. The server reads the cookie on the next request.
+
+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.
+
+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.
+
+## Full API Reference
+
+For the complete API reference — all function signatures, type definitions, OAuth helpers, admin operations, session management, auth events, and framework-specific examples — read the package README:
+
+```
+node_modules/@netlify/identity/README.md
+```
+
+The README is shipped with the npm package and is always in sync with the installed version.

package/dist/skills/netlify-identity/references/authorization-and-sessions.md

@@ -0,0 +1,24 @@
+# Netlify Identity — authorization and session gotchas
+
+Where role-based access actually gets enforced, and why a role change doesn't take effect immediately.
+
+## Admin operations run only in the Functions runtime
+
+Identity's admin API — creating users, updating a user's roles or metadata, deleting users (the `admin.*` operations) — requires a privileged admin token that is available **only in the Netlify Functions runtime**. It is not exposed to browser code and is not available in Edge Functions. Do all role assignment and user administration from inside a modern v2 Function (or an Identity event function), never from the client and never from an edge function. A "promote this user to admin" button in the UI must call a Function endpoint that performs the change server-side — it cannot call the admin API directly from the browser.
+
+You don't configure or read the admin token yourself — the Netlify Functions runtime provides it automatically to `admin.*` calls made inside a Function, so there is no env var to set and no `Netlify.env.get(...)` to call for it. Run the `admin.*` operations server-side in a Function; never hardcode an admin token, ship one in the client bundle, or expose the admin operations to the browser. Exposing an admin capability client-side would let any visitor grant themselves the `admin` role.
+
+## Redirect gating only covers CDN document requests
+
+`conditions = { Role = [...] }` redirects are enforced by the CDN **only when it serves a document (navigation) request** — a fresh HTTP request for the path. They are a coarse page-level perimeter, not real authorization:
+
+- **SPA client-side navigation bypasses them.** When a client-side router (React, Vue, SvelteKit, etc.) navigates to `/admin` in the browser, no new document request reaches the CDN, so the redirect rule never runs and the route renders regardless of the user's role.
+- **Anything in the client bundle is downloadable by anyone.** Role-gated content compiled into the JavaScript bundle ships to every visitor who can load the page; hiding a component behind a client-side role check does not protect the data inside it.
+
+So use redirect gating for coarse routing only. Enforce anything sensitive **server-side on every request** — a Netlify Function (or the API it calls) that resolves the user with `getUser()` and checks the server-controlled `app_metadata.roles` — never a client-side route guard or a hidden UI element as the only gate.
+
+## Role changes don't affect live sessions until the JWT refreshes
+
+Roles are baked into the `nf_jwt` when the token is issued, and that JWT stays valid until it expires (about an hour). Changing a user's roles — via the dashboard, the admin API, or an Identity event function — does **not** update tokens already held by signed-in users. A user you just promoted keeps seeing the old view, and a user whose role you just revoked keeps their access, until their token refreshes (`AUTH_EVENTS.TOKEN_REFRESH`) or they log out and log back in. Both redirect `Role` conditions and function-side `app_metadata.roles` checks read the current token, so both see the stale roles until then.
+
+Don't expect a role change to take effect mid-session. When it needs to apply right away, direct the user to log out and back in (or otherwise refresh their token) so a new `nf_jwt` carrying the updated roles is issued.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@netlify/agent-runner-cli",
   "type": "module",
-  "version": "2.16.0-server.1",
+  "version": "2.16.0-server.3",
   "description": "CLI tool for running Netlify agents",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -48,6 +48,7 @@
     "check:types": "tsc --noEmit",
     "prompts": "LOG=0 vitest run --config vitest.prompts.config.js",
     "site:build": "npm run prompts && node site/build.mjs",
+    "site:dev": "npm run site:build && netlify dev --dir site/dist",
     "postinstall": "node scripts/postinstall.js"
   },
   "engines": {

package/scripts/build-skills.js

@@ -1,4 +1,5 @@
-import { appendFile, cp, mkdir, readdir, readFile, rm } from 'node:fs/promises'
+import { existsSync } from 'node:fs'
+import { cp, mkdir, readdir, readFile, rm, writeFile } from 'node:fs/promises'
 import { createRequire } from 'node:module'
 import path from 'node:path'
 import process from 'node:process'
@@ -8,34 +9,55 @@ const localSkillsDir = new URL('../src/skills/', import.meta.url)
 const sharedPackagePath = createRequire(import.meta.url).resolve('@netlify/skills/package.json')
 const sharedSkillsDir = path.join(path.dirname(sharedPackagePath), 'skills')
 export const bundledSkillsDir = fileURLToPath(new URL('../dist/skills/', import.meta.url))
-const selectedSharedSkills = [
-  { name: 'netlify-access-control' },
-  {
-    name: 'netlify-forms',
-    instructions: new URL('../src/skill-instructions/netlify-forms.md', import.meta.url),
-    assets: new URL('../src/skill-assets/netlify-forms/', import.meta.url),
-  },
-  {
-    name: 'netlify-image-cdn',
-    instructions: new URL('../src/skill-instructions/netlify-image-cdn.md', import.meta.url),
-  },
-]
+const skillOverridesDir = fileURLToPath(new URL('../src/skill-overrides/', import.meta.url))
+export const selectedSharedSkills = ['netlify-access-control', 'netlify-forms', 'netlify-image-cdn', 'netlify-identity']
+
+const readOptionalFile = async (filePath) => {
+  try {
+    return await readFile(filePath, 'utf8')
+  } catch (error) {
+    if (error.code === 'ENOENT') return undefined
+    throw error
+  }
+}
+
+export const applySkillReplacements = (content, replacements) => {
+  let result = content
+  for (const { from, to } of replacements) {
+    if (!from || result.split(from).length !== 2) {
+      throw new Error(`Expected exactly one occurrence of shared skill text: ${JSON.stringify(from)}`)
+    }
+    result = result.replace(from, () => to)
+  }
+  return result
+}
 
 export const buildSkills = async (targetDir = bundledSkillsDir) => {
   await rm(targetDir, { recursive: true, force: true })
   await cp(localSkillsDir, targetDir, { recursive: true })
 
-  for (const { name, instructions, assets } of selectedSharedSkills) {
+  for (const name of selectedSharedSkills) {
     await cp(path.join(sharedSkillsDir, name), path.join(targetDir, name), {
       recursive: true,
       force: false,
       errorOnExist: true,
     })
-    if (instructions) {
-      await appendFile(path.join(targetDir, name, 'SKILL.md'), `\n\n${await readFile(instructions, 'utf8')}`)
+    const overrideDir = path.join(skillOverridesDir, name)
+    const replacements = await readOptionalFile(path.join(overrideDir, 'replacements.json'))
+    const instructions = await readOptionalFile(path.join(overrideDir, 'instructions.md'))
+    if (instructions !== undefined || replacements !== undefined) {
+      const skillPath = path.join(targetDir, name, 'SKILL.md')
+      let content = await readFile(skillPath, 'utf8')
+      if (replacements !== undefined) {
+        content = applySkillReplacements(content, JSON.parse(replacements))
+      }
+      if (instructions !== undefined) {
+        content += `\n\n${instructions}`
+      }
+      await writeFile(skillPath, content)
     }
-    if (assets) {
-      const assetsDir = fileURLToPath(assets)
+    const assetsDir = path.join(overrideDir, 'assets')
+    if (existsSync(assetsDir)) {
       for (const entry of await readdir(assetsDir, { recursive: true, withFileTypes: true })) {
         if (!entry.isFile()) continue
         const source = path.join(entry.parentPath, entry.name)