@netlify/agent-runner-cli 2.17.0-PAW-612.0 → 2.18.0-smtp.0

package/dist/skills/general-backend@backend/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: general-backend
+description: Use this skill whenever the task involves server-side code — API endpoints, backend logic, request handlers, WebSockets, server-side AI calls, auth checks, or any code that must run on a server rather than in the browser. Covers Netlify Server, Netlify Functions, Edge Functions, and full-stack framework server routes.
+---
+
+# Server-side code on Netlify
+
+Where server-side code goes depends on the project. Work out which case applies before writing code, and for a
+new project, before scaffolding a template.
+
+## New project that needs a Netlify Server: no template
+
+The create-mode templates are built on a full-stack framework that deploys its server-side rendering as a Netlify
+Function on every path, so a Netlify Server added to a template project never receives requests. If the project
+needs a Netlify Server, don't scaffold a template. A new project needs one when it has any request-driven backend
+code: API endpoints, data saved and read through the backend, WebSockets, server-side AI calls, or an HTTP server
+framework such as Express, Hono, or Fastify.
+
+A site with no backend code (static pages, a marketing or content site, a client-only tool) needs neither a server
+nor functions. Use the templates as usual for it.
+
+## Project with a full-stack framework: use its server routes
+
+Full-stack frameworks (such as TanStack Start, Next.js, Astro, SvelteKit, Remix, Nuxt) build
+their own server code into Netlify Functions at deploy time. In these projects, put request handling in the
+framework's server routes or server functions instead of adding a Netlify Server. Call Netlify Database, Blobs, and
+the AI Gateway from those routes. Use Netlify Functions alongside them only for the cases listed under "Only when
+Server can't" below.
+
+HTTP server frameworks such as Express, Hono, Fastify, and Koa are different: nothing deploys them for you, so they
+run as a Netlify Server, covered next.
+
+## Otherwise: Netlify Server
+
+**Netlify Server** runs one long-running Node.js process (Express, Hono, Fastify, or plain `node:http`) from
+`netlify/server/index.mjs`. Put every request-driven piece of backend code in it:
+
+- API endpoints and route handlers
+- Server-rendered pages and form handling in your own routes
+- WebSockets and streaming responses
+- Calls to the Netlify AI Gateway, Netlify Database, and Netlify Blobs
+- Short work that continues after the response (seconds, such as sending an email), registered with `waitUntil`
+- Auth checks, webhooks from third-party services, proxies to external APIs
+
+Don't pick Functions just because the task is small or looks like a single endpoint.
+
+See the **netlify-server** skill for complete setup instructions and usage examples.
+
+## Only when Server can't: Netlify Functions
+
+Use **Netlify Functions** alongside the server only for:
+
+- **Scheduled functions**: work that runs on a cron schedule, with no incoming request.
+- **Event handlers**: code triggered by platform events, such as Netlify Forms submissions, Netlify Identity events
+  (signup, login, validate), or deploy events.
+- **Background functions**: jobs that can run longer than about a minute and must not be cut off midway, such as
+  generating a report or processing an upload (up to 15 minutes). When a server instance is replaced by a deploy or
+  scaling event, its background work gets only 90 seconds to finish. The server enqueues the job by calling the
+  background function and returns right away.
+
+Scheduled functions and event handlers run without an incoming request, which a server can't do, and background
+functions aren't cut off when a server instance is replaced. Everything else stays in the server, including the
+endpoints these functions talk to.
+
+See the **netlify-functions** skill for complete setup instructions and usage examples.
+
+## Request and response changes at the edge: Edge Functions
+
+Use **Edge Functions** for logic that runs on every request before it reaches the server or the site: rewrites and
+redirects based on geolocation or cookies, A/B tests, header changes, or lightweight auth checks. They run in Deno
+close to visitors and don't replace the server for application logic.
+
+See the **netlify-edge-functions** skill for setup instructions.
+
+## Existing projects
+
+If an existing project already serves its backend from `netlify/functions/`, keep using that for changes to it.
+Don't migrate an existing backend to a Netlify Server unless asked.

package/dist/skills/netlify-functions/SKILL@backend.md

@@ -0,0 +1,610 @@
+---
+name: netlify-functions
+description: Create and deploy Netlify Functions. Use for scheduled tasks, background jobs that can run longer than about a minute, and platform event handlers (Forms submissions, Identity events, deploy events). For API endpoints and other server-side logic, use the netlify-server skill instead.
+---
+
+# Netlify Functions
+
+Netlify Functions are serverless API endpoints and background workers that deploy alongside your site. They use
+standard Web API Request/Response objects with zero configuration required.
+
+Server-side code goes in a Netlify Server by default (see the `general-backend` and `netlify-server` skills).
+Write functions only for [Scheduled Functions](#scheduled-functions), [Event Handlers](#event-handlers), and
+[Background Functions](#background-functions) for jobs that can run longer than about a minute, or when
+changing a project that already serves its backend from `netlify/functions/`.
+
+## Quick Start
+
+Create a function file in the `netlify/functions/` directory:
+
+```typescript
+// netlify/functions/hello.mts
+export default async (req: Request) => {
+  const name = new URL(req.url).searchParams.get('name') || 'world'
+  return new Response(`Hello, ${name}!`)
+}
+```
+
+```javascript
+// netlify/functions/hello.mjs
+export default async (req) => {
+  const name = new URL(req.url).searchParams.get('name') || 'world'
+  return new Response(`Hello, ${name}!`)
+}
+```
+
+Deploy and invoke at `/.netlify/functions/hello?name=Netlify`.
+
+ALWAYS use TypeScript (`.mts`) if other functions in the project are TypeScript or if there are no existing functions.
+ONLY use vanilla JavaScript if there are other `.js` files in the functions directory. DO NOT put global logic outside
+of the exported function unless wrapped in a function definition. ALWAYS use the latest format of a function structure.
+
+Serverless functions use Node.js and should attempt to use built-in methods where possible.
+
+When adding new npm modules, ensure `node_modules` is in the `.gitignore`. If using TypeScript, ensure types are
+installed from `npm install @netlify/functions`.
+
+## Function Structure & Placement
+
+**Default directory:** `netlify/functions/` (relative to site base directory)
+
+**Naming conventions:**
+- Use `.mts` (TypeScript, recommended) or `.mjs` (JavaScript) extensions. Naming files with `.mts` enables modern ES module syntax
+- Filename becomes the function name and default URL path
+- One default export per file
+
+**Valid function paths:**
+- `netlify/functions/hello.mts`
+- `netlify/functions/hello/index.mts`
+- `netlify/functions/hello/hello.mts`
+
+**Custom directory** via `netlify.toml`:
+
+```toml
+[functions]
+directory = "my_functions"
+```
+
+## Handler Signature
+
+```typescript
+export default async (req: Request, context: Context) => Response | void
+```
+
+The handler receives a standard [Web API Request](https://developer.mozilla.org/en-US/docs/Web/API/Request) and a
+Netlify-specific `Context` object. Return a standard
+[Web API Response](https://developer.mozilla.org/en-US/docs/Web/API/Response), or return nothing for a 204 response.
+
+```typescript
+import type { Context } from '@netlify/functions'
+
+export default async (req: Request, context: Context) => {
+  const body = await req.json()
+  return Response.json({ received: body })
+}
+```
+
+## In-Code Config & Routing
+
+Prefer to use in-code configuration via exporting a `config` object. Prefer to provide a friendly path using the config
+object. ONLY serverless functions use `/.netlify/functions/{function_name}` path by default. If you set a specific path
+via config or netlify.toml, it will only be available at that new path.
+
+Export a `config` object to configure routing and behavior:
+
+```typescript
+import type { Config } from '@netlify/functions'
+
+export default async (req: Request, context: Context) => {
+  const { name } = context.params
+  return Response.json({ pet: name })
+}
+
+export const config: Config = {
+  path: '/api/pets/:name',
+}
+```
+
+**Config properties:**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `path` | `string \| string[]` | Custom URL path(s) with route parameters |
+| `excludedPath` | `string \| string[]` | Paths to exclude from matching |
+| `preferStatic` | `boolean` | If `true`, static file takes precedence over function |
+| `method` | `string \| string[]` | HTTP method(s) to match (`GET`, `POST`, etc.) |
+| `schedule` | `string` | Cron expression for scheduled functions |
+| `background` | `boolean` | If `true`, run in background mode (fire-and-forget) |
+
+`path` and `excludedPath` support substring patterns or the URLPattern syntax from the web platform.
+
+**Route parameters:**
+
+```typescript
+// :param - named parameter
+export const config: Config = { path: '/api/users/:id' }
+// context.params.id = '123' for /api/users/123
+
+// * - wildcard
+export const config: Config = { path: '/api/*' }
+// Matches /api/anything/here
+```
+
+**Multiple paths:**
+
+```typescript
+export const config: Config = {
+  path: ['/api/pets/:name', '/api/animals/:name'],
+}
+```
+
+## Context Object
+
+The `context` parameter provides Netlify-specific metadata:
+
+### `context.ip`
+
+Client IP address as a string.
+
+### `context.geo`
+
+Geolocation data for the client:
+
+```typescript
+context.geo.city        // string - city name
+context.geo.country     // { code: string, name: string } - ISO 3166
+context.geo.latitude    // number
+context.geo.longitude   // number
+context.geo.subdivision // { code: string, name: string } - ISO 3166
+context.geo.timezone    // string - IANA timezone
+context.geo.postalCode  // string
+```
+
+### `context.site`
+
+Site metadata:
+
+```typescript
+context.site.id   // string - unique site ID
+context.site.name // string - site subdomain name
+context.site.url  // string - primary site URL
+```
+
+### `context.deploy`
+
+Deploy metadata:
+
+```typescript
+context.deploy.context   // string - deploy context (e.g., 'production', 'deploy-preview')
+context.deploy.id        // string - unique deploy ID
+context.deploy.published // boolean - is this the published deploy?
+```
+
+### `context.account`
+
+```typescript
+context.account.id // string - team/account ID
+```
+
+### `context.requestId`
+
+Unique request identifier string.
+
+### `context.params`
+
+Route parameters from `config.path`:
+
+```typescript
+// For path '/api/users/:id' and request '/api/users/42':
+context.params.id // '42'
+```
+
+### `context.cookies`
+
+Simplified cookie interface:
+
+```typescript
+// Read
+const session = context.cookies.get('session')
+
+// Set
+context.cookies.set({ name: 'session', value: 'abc123', path: '/', httpOnly: true })
+
+// Delete
+context.cookies.delete('session')
+```
+
+### `context.server`
+
+```typescript
+context.server.region // string - e.g., 'us-east-1'
+```
+
+### `context.user`
+
+The user who signed in through Netlify's SSO to reach a private project or a site protected by Netlify team login.
+`undefined` when the request didn't come from such a user. Netlify verifies the visitor and sets this itself, so it
+can't be spoofed with request headers.
+
+```typescript
+context.user.id        // string - user ID
+context.user.email     // string - user email address
+context.user.expiresAt // Date - when the user's access expires
+```
+
+```typescript
+// netlify/functions/whoami.mts
+import type { Config, Context } from '@netlify/functions'
+
+export default async (req: Request, context: Context) => {
+  if (!context.user) return new Response('Unauthorized', { status: 401 })
+  return Response.json({
+    id: context.user.id,
+    email: context.user.email,
+    expiresAt: context.user.expiresAt.toISOString(),
+  })
+}
+
+export const config: Config = { path: '/whoami' }
+```
+
+This is the Netlify team member viewing the site, not a Netlify Identity user; for end-user accounts on your site use
+the `netlify-identity` skill. See the
+[changelog post](https://www.netlify.com/changelog/2026-10-07-context-user-in-functions/) and the
+[Functions API docs](https://docs.netlify.com/build/functions/api/#user).
+
+### `context.waitUntil(promise)`
+
+Extends execution after the response is sent. Use for analytics, logging, or cleanup tasks.
+
+```typescript
+export default async (req: Request, context: Context) => {
+  context.waitUntil(
+    fetch('https://analytics.example.com/track', {
+      method: 'POST',
+      body: JSON.stringify({ path: new URL(req.url).pathname }),
+    }),
+  )
+  return new Response('OK')
+}
+```
+
+## Global `Netlify` Object
+
+Available in all function contexts:
+
+### `Netlify.env`
+
+Access environment variables:
+
+```typescript
+const apiKey = Netlify.env.get('API_KEY')     // string | undefined
+const exists = Netlify.env.has('API_KEY')      // boolean
+const all = Netlify.env.toObject()             // Record<string, string>
+
+// Scoped to current invocation only
+Netlify.env.set('TEMP_VAR', 'value')
+Netlify.env.delete('TEMP_VAR')
+```
+
+ALWAYS use `Netlify.env.get()` instead of `process.env` when reading environment variables in Netlify Functions. It
+provides consistent behavior across all function contexts.
+
+### `Netlify.context`
+
+Same as the `context` parameter in the handler. Available from outside the handler scope (e.g., imported modules).
+Returns `null` outside a function invocation.
+
+## Background Functions
+
+Background functions operate the same as standard serverless functions and are syntactically the same. They run for up
+to 15 minutes without blocking the client. The client receives an immediate 202 response.
+
+Enable background mode by setting `background: true` in the function's config:
+
+```typescript
+// netlify/functions/process-data.mts
+import type { Config, Context } from '@netlify/functions'
+
+export default async (req: Request, context: Context) => {
+  const data = await req.json()
+
+  // Long-running work (up to 15 minutes)
+  for (const item of data.items) {
+    await processItem(item)
+  }
+
+  // Return value is ignored - client already received 202
+}
+
+export const config: Config = {
+  background: true,
+}
+```
+
+```javascript
+// netlify/functions/process-data.mjs
+export default async (req, context) => {
+  const data = await req.json()
+
+  for (const item of data.items) {
+    await processItem(item)
+  }
+}
+
+export const config = {
+  background: true,
+}
+```
+
+**Key behavior:**
+- Client receives `202 Accepted` immediately
+- Function continues executing for up to 15 minutes
+- Response body is ignored
+- No streaming support
+- Cannot use `config.schedule`
+- Retry logic: first retry after 1 minute, second retry after 2 minutes on failure
+- Any data background functions produce should be stored in Netlify Blobs or a database
+
+**Legacy filename convention:** Naming the file with a `-background` suffix (e.g., `process-data-background.mts`) is still
+supported and continues to work. New functions should prefer the `config.background` property above.
+
+Invoke like any function: `POST /.netlify/functions/process-data` (or use the `path` config property).
+
+## Scheduled Functions
+
+Run functions on a cron schedule. Use for periodic tasks like data sync, cleanup, or report generation.
+
+```typescript
+// netlify/functions/daily-cleanup.mts
+import type { Config } from '@netlify/functions'
+
+export default async (req: Request) => {
+  const { next_run } = await req.json()
+  console.log('Running cleanup. Next run:', next_run)
+
+  await performCleanup()
+}
+
+export const config: Config = {
+  schedule: '@daily',
+}
+```
+
+```javascript
+// netlify/functions/daily-cleanup.mjs
+export default async (req) => {
+  const { next_run } = await req.json()
+  console.log('Running cleanup. Next run:', next_run)
+
+  await performCleanup()
+}
+
+export const config = {
+  schedule: '@daily',
+}
+```
+
+The minimum interval is 1 minute. Scheduled functions do not return response bodies.
+
+**Cron syntax** (UTC timezone):
+
+```
+ ┌───────────── minute (0-59)
+ │ ┌───────────── hour (0-23)
+ │ │ ┌───────────── day of month (1-31)
+ │ │ │ ┌───────────── month (1-12)
+ │ │ │ │ ┌───────────── day of week (0-6, Sunday=0)
+ │ │ │ │ │
+ * * * * *
+```
+
+**Supported extensions:**
+
+| Extension | Equivalent | Description |
+|-----------|------------|-------------|
+| `@yearly` | `0 0 1 1 *` | January 1st at midnight |
+| `@monthly` | `0 0 1 * *` | 1st of each month at midnight |
+| `@weekly` | `0 0 * * 0` | Sunday at midnight |
+| `@daily` | `0 0 * * *` | Every day at midnight |
+| `@hourly` | `0 * * * *` | Every hour at minute 0 |
+
+Cron syntax supports extensions defined in the RFC except for `@reboot` and `@annually`.
+
+**Alternative:** Configure schedule in `netlify.toml` instead of in-code config. ONLY do this for consistency or if
+explicitly asked to keep all schedules in one place:
+
+```toml
+[functions."daily-cleanup"]
+schedule = "@daily"
+```
+
+**Key behavior:**
+- Scheduled functions only run on **published deploys** (not deploy previews or branch deploys)
+- Request body is `{ "next_run": "<ISO-8601 timestamp>" }`
+- 30-second execution time limit (use background functions for longer tasks)
+- No direct URL invocation in production
+
+**Local testing:**
+
+```bash
+netlify functions:invoke daily-cleanup
+```
+
+## Region
+
+Functions deploy to `cmh` (Ohio) by default. This is a deliberate choice: US East is centrally located for an international audience, has a broad provider ecosystem, and gives most projects the lowest overall latency without any configuration.
+
+Do NOT override `config.region` unless the user has stated a specific reason — for example, a database or backend service in another region with measurable roundtrip savings, a data-residency requirement, or an audience concentrated in one region whose compute dependencies (database, backend services) also live in that region.
+
+Two constraints to be aware of before adding `config.region`:
+
+- A function runs in exactly one region. Don't try to deploy the same function to multiple regions — if the user wants geo-routing, route between distinct functions with an edge function instead.
+- For framework adapter–generated functions (Next.js, Astro, Nuxt, etc.) the region must be set site-wide in the Netlify UI, not via `config.region` in code. The generated files can't carry per-function config.
+
+See [Region](https://docs.netlify.com/build/functions/configuration#region) for the full list of supported regions and details.
+
+## Memory or vCPU
+
+Functions run with 1024 MB of memory and a proportional amount of compute by default. The default fits most workloads, and raising it has a direct cost impact: function billing scales linearly with the configured size.
+
+Do NOT set `config.memory` or `config.vcpu` speculatively. Only reach for them when:
+
+- The workload is known to be memory- or compute-intensive (AI inference, image/PDF manipulation, large payload processing, CPU-bound work).
+- The function is hitting out-of-memory errors or timeouts caused by the function's own work, rather than by waiting on an external service or database.
+
+`memory` and `vcpu` configure the same underlying resource and are mutually exclusive — set one, not both. See [Memory or vCPU](https://docs.netlify.com/build/functions/configuration#memory-or-vcpu) for accepted values and the exact mapping.
+
+## Response Streaming
+
+Synchronous functions can stream responses for large payloads (up to 20 MB):
+
+```typescript
+export default async (req: Request) => {
+  const stream = new ReadableStream({
+    start(controller) {
+      controller.enqueue(new TextEncoder().encode('Hello '))
+      controller.enqueue(new TextEncoder().encode('World'))
+      controller.close()
+    },
+  })
+
+  return new Response(stream, {
+    headers: { 'Content-Type': 'text/plain' },
+  })
+}
+```
+
+## Event Handlers
+
+A function can subscribe to platform events by exporting an object instead of a function as its default. Each event has
+a named handler property.
+
+```typescript
+import type { DeploySucceededEvent, UserSignupEvent } from '@netlify/functions'
+
+export default {
+  deploySucceeded(event: DeploySucceededEvent) {
+    console.log(`Deploy ${event.deploy.id} succeeded`)
+  },
+
+  userSignup(event: UserSignupEvent) {
+    return {
+      user: {
+        ...event.user,
+        appMetadata: { ...event.user.appMetadata, roles: ['member'] },
+      },
+    }
+  },
+}
+```
+
+A single function can declare multiple handlers; multiple functions can also subscribe to the same event — both will run.
+
+The default export can also be an object with a `fetch` method instead of a bare function. Prefer the bare default export shown in [Handler Signature](#handler-signature); reach for the object form only if (1) other functions in the project already use it, or (2) the same function handles HTTP requests AND subscribes to one or more platform events:
+
+```typescript
+export default {
+  fetch(req: Request, context: Context) {
+    return new Response('Hello')
+  },
+}
+```
+
+**Available handlers:**
+
+| Handler | Trigger |
+|---|---|
+| `fetch` | HTTP request (equivalent to a bare function default export) |
+| `deployBuilding`, `deploySucceeded`, `deployFailed`, `deployDeleted`, `deployLocked`, `deployUnlocked` | Deploy lifecycle |
+| `userSignup`, `userLogin`, `userValidate`, `userModified`, `userDeleted` | Identity lifecycle |
+| `formSubmitted` | Form submission verified |
+
+### Identity handlers: deny an action
+
+`userSignup`, `userLogin`, `userValidate`, and `userModified` can reject the action by calling `event.deny()`. The end user
+receives a 401. Do NOT throw — `event.deny()` is the canonical denial mechanism and does not produce an error in observability.
+
+```typescript
+import type { UserLoginEvent } from '@netlify/functions'
+
+export default {
+  userLogin(event: UserLoginEvent) {
+    if (!event.user.email?.endsWith('@example.com')) {
+      return event.deny()
+    }
+  },
+}
+```
+
+If multiple functions subscribe to the same event, the first to call `event.deny()` aborts the chain.
+
+## Limits
+
+| Resource | Limit |
+|----------|-------|
+| Memory | 1024 MB |
+| Synchronous execution time | 60 seconds |
+| Scheduled execution time | 30 seconds |
+| Background execution time | 15 minutes |
+| Buffered request/response payload | 6 MB |
+| Background function payload | 256 KB |
+| Streaming response payload | 20 MB |
+| Functions per site | Unlimited |
+
+## Common Errors & Solutions
+
+### "Function not found" (404)
+
+**Cause:** Function file not in the correct directory or wrong extension.
+
+**Fix:**
+
+1. Place function in `netlify/functions/` (or configured directory)
+2. Use `.mts` or `.mjs` extension (not `.ts` or `.js`)
+3. Ensure the file has a default export
+
+### "Function timeout" (502 or 504)
+
+**Cause:** Function exceeds execution time limit.
+
+**Fix:**
+
+1. Synchronous functions: optimize to complete within 60 seconds
+2. For long-running tasks, use background functions (`-background` suffix, 15-min limit)
+3. For periodic tasks, use scheduled functions
+
+### "Payload too large" (413)
+
+**Cause:** Request or response exceeds 6 MB limit.
+
+**Fix:**
+
+1. Reduce payload size
+2. For large file handling, use Netlify Blobs for storage and pass references instead of raw data
+3. Use streaming responses for large outputs (up to 20 MB)
+
+### "CORS errors" in browser
+
+**Cause:** Missing CORS headers on function response. NEVER add CORS headers unless explicitly requested by the user.
+
+**Fix** (only when user asks for CORS support):
+
+```typescript
+return new Response(JSON.stringify(data), {
+  headers: {
+    'Content-Type': 'application/json',
+    'Access-Control-Allow-Origin': '*',
+  },
+})
+```
+
+### Environment variable is undefined
+
+**Cause:** Variable not available in the function context.
+
+**Fix:**
+
+1. Use `Netlify.env.get('VAR_NAME')` instead of `process.env.VAR_NAME`
+2. Ensure the variable is set in Netlify UI with correct scopes (Runtime)
+3. Deploy to Netlify or use the Vite plugin for env var injection