@netlify/agent-runner-cli 1.164.0 → 1.165.0

package/dist/skills/netlify-server@netlifyserver/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: netlify-server
+description: Run a long-running HTTP server (Express, Hono, Fastify, or plain node:http) on Netlify. ONLY use when the prompt explicitly asks for a Netlify Server by name. Never select this primitive on your own initiative.
+---
+
+# Netlify Server
+
+A Netlify Server is one long-running Node.js process deployed alongside your site. Unlike Netlify Functions, which run per request, the server process is started once, reused across requests, scaled to zero when idle, and started again on the next request. It runs standard Node.js servers with no Netlify-specific APIs: if it listens on a port, it works.
+
+## When to use this skill: explicit request only
+
+Netlify Server is an experimental primitive. The rule for choosing it is strict:
+
+- ONLY build with a Netlify Server when the prompt **explicitly requests a "Netlify Server"** by name (for example "build this as a Netlify Server" or "use the Netlify Server primitive").
+- If the prompt does not name it, discard this skill entirely, even when the request mentions Express, Hono, WebSockets, servers in general, or would otherwise seem like a good fit. In those cases use **Netlify Functions** (see the `netlify-functions` skill) and the other platform primitives as usual.
+- NEVER migrate an existing site's functions to a Netlify Server unless explicitly asked to.
+
+Once a Netlify Server has been explicitly requested: implement all API routes inside the server app, and do NOT create files in `netlify/functions/` alongside it.
+
+## Quick start
+
+Create exactly one entrypoint at `netlify/server/index.mjs`. Any Node.js server works. It MUST listen on `process.env.PORT`.
+
+Express:
+
+```javascript
+// netlify/server/index.mjs
+import express from 'express'
+
+const app = express()
+
+app.get('/api/hello', (req, res) => {
+  res.json({ hello: 'world' })
+})
+
+app.listen(process.env.PORT)
+```
+
+Hono (no `listen` call; export the app as the default export):
+
+```javascript
+// netlify/server/index.mjs
+import { Hono } from 'hono'
+
+const app = new Hono()
+
+app.get('/api/hello', (c) => c.json({ hello: 'world' }))
+
+export default app
+```
+
+Declare dependencies in `package.json` as usual. Deploy is the normal site deploy; nothing extra to configure. The build log confirms detection with the line `Netlify Server detected at netlify/server/index.mjs`.
+
+## Rules
+
+- **One entrypoint only.** `netlify/server/` must contain exactly one of `index.mjs`, `index.js`, `index.ts`, or `index.mts`. Two entry files fail the build. Prefer `index.mjs` with ESM syntax; split the rest of the server into modules that the entrypoint imports.
+- **Listen on `process.env.PORT`.** It is set before your code is imported. Do not hardcode a port.
+- **Do not daemonize, fork, or spawn long-lived child processes.** One process serves the traffic.
+- Environment variables work as usual via `process.env`.
+- When adding npm modules, ensure `node_modules` is in `.gitignore`.
+
+## Routing and static files
+
+The server receives every request that is not served as a static file:
+
+- Files in the publish directory win over the server for matching paths (`preferStatic`). Use the publish directory for assets like images, fonts, or a favicon.
+- Do NOT put an `index.html` in the publish directory if the server should render `/`. A static `index.html` shadows the server's root route.
+- There is no path prefix: the server sees `/`, `/api/anything`, and everything else, with the original paths.
+
+## Lifecycle: scale to zero
+
+This is the most important mental model for building correctly:
+
+- After a period with no traffic, the server is shut down. The next request starts a fresh process (a cold start).
+- **All process memory is lost on every scale-to-zero, deploy, and platform maintenance event.** In-memory caches are fine as caches; they are NEVER storage. Anything that must survive belongs in Netlify Blobs or Netlify Database (see the `general-database` skill to choose).
+- In-flight requests are never cut off by the idle shutdown.
+- Background work that outlives the request that triggered it (for example, responding early and then finishing a task) MUST be registered with `getContext().waitUntil(promise)`. Registered work keeps the process alive until the promise settles; unregistered work may be reclaimed the moment no requests are active.
+- `waitUntil` extends the idle lifetime, but deploys and platform maintenance still stop the process with only a short grace window. Keep background tasks short (seconds, not minutes), and persist anything critical before responding. For genuinely long jobs, persist a job record and process it in resumable increments across requests.
+
+Graceful shutdown hook (optional): export a `shutdown` function from the entrypoint; it is called before the process is stopped. Keep it fast (a few seconds), for example flushing a buffer to Blobs. For Express-style apps that call `listen`, you can also listen for `SIGTERM` directly.
+
+```javascript
+export const shutdown = async () => {
+  await flushPendingWrites()
+}
+```
+
+## Request context: geolocation, cookies, site metadata
+
+Inside request handling, get the Netlify request context with `getContext` from the `@netlify/functions` package (add it to `package.json`):
+
+```javascript
+import express from 'express'
+import { getContext } from '@netlify/functions'
+
+const app = express()
+
+app.get('/api/where', (req, res) => {
+  const context = getContext()
+  res.json({ city: context.geo?.city, country: context.geo?.country?.name })
+})
+
+app.listen(process.env.PORT)
+```
+
+Rules:
+
+- ONLY call `getContext()` while handling a request (inside a route handler, middleware, or code awaited from one). It throws outside a request.
+- Works with every server form, including WebSocket upgrade handling.
+
+## AI inference: Netlify AI Gateway
+
+The AI Gateway works with zero configuration: provider credentials and base URLs (`OPENAI_API_KEY`, `OPENAI_BASE_URL`, and equivalents for other providers) are injected into `process.env` automatically. See the `netlify-ai-gateway` skill for supported models and usage.
+
+One rule specific to servers: **construct AI SDK clients inside request handling, never at module scope.** Credentials are injected per request, so they do not exist when the module is first imported.
+
+```javascript
+import OpenAI from 'openai'
+
+app.post('/api/chat', async (req, res) => {
+  const client = new OpenAI() // created per request: credentials are available here
+  // ...
+})
+```
+
+## WebSockets
+
+WebSockets work for servers that handle HTTP upgrades (the `listen` form). Attach the WebSocket server to the same HTTP server:
+
+```javascript
+// netlify/server/index.mjs
+import express from 'express'
+import { WebSocketServer } from 'ws'
+
+const app = express()
+const server = app.listen(process.env.PORT)
+const wss = new WebSocketServer({ noServer: true })
+
+server.on('upgrade', (req, socket, head) => {
+  if (req.url !== '/ws') {
+    socket.destroy()
+    return
+  }
+  wss.handleUpgrade(req, socket, head, (ws) => {
+    ws.send('connected')
+  })
+})
+```
+
+Rules for WebSocket clients you generate:
+
+- ALWAYS implement automatic reconnection with backoff in the browser client. The platform may terminate long-lived connections periodically; a reconnecting client makes this invisible to users.
+- Do not rely on a socket staying open indefinitely, and do not keep client state only on the server side of a socket: rebuild the needed state on reconnect.
+
+## Common mistakes
+
+- Treating process memory as a database. It is wiped on every cold start. Use Blobs or Database.
+- Hardcoding a port or defaulting to `3000` without reading `process.env.PORT` first.
+- Adding an `index.html` to the publish directory that shadows the server's `/` route.
+- Creating `netlify/functions/` endpoints alongside the server. Put API routes in the server app.
+- Two entry files in `netlify/server/` (for example both `index.mjs` and `index.ts`). Keep one.
+- Fire-and-forget background jobs without `getContext().waitUntil(promise)`. Unregistered work may be reclaimed mid-flight; registered work should still be short and non-critical.
+- Constructing AI SDK clients (or calling `getContext()`) at module scope. Per-request state does not exist at import time.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@netlify/agent-runner-cli",
   "type": "module",
-  "version": "1.164.0",
+  "version": "1.165.0",
   "description": "CLI tool for running Netlify agents",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -42,6 +42,7 @@
     "test:integration:codex": "vitest run test/integration/codex.test.ts",
     "test:integration:claude": "vitest run test/integration/claude.test.ts",
     "test:integration:gemini": "vitest run test/integration/gemini.test.ts",
+    "test:integration:opencode": "vitest run test/integration/opencode.test.ts",
     "test:integration:skill-invocation": "vitest run test/integration/skill-invocation.test.ts",
     "check:types": "tsc --noEmit",
     "postinstall": "node scripts/postinstall.js"