opencode-skills-collection 3.1.12 → 3.1.14

package/bundled-skills/neon-functions/references/sse.md

@@ -0,0 +1,143 @@
+# Server-sent events (SSE) on Neon Functions
+
+SSE is the one-way (server → client) streaming counterpart to WebSockets: the browser opens a long-lived `GET` with [`EventSource`](https://developer.mozilla.org/en-US/docs/Web/API/EventSource) and the server pushes text frames down it. On Neon Functions there's **no adapter or extra library to install** — unlike the [Hono WebSocket helper](hono-websockets.md), an SSE endpoint is just a normal `fetch` handler that returns a `Response` whose body is a `ReadableStream` with `Content-Type: text/event-stream`. The runtime holds the response open as long as bytes keep flowing (15-minute heartbeat, see [Timeouts](../SKILL.md#timeouts-and-runtime-limits)).
+
+Reach for SSE over WebSockets when you only need server → client updates (live counters, notifications, progress, token streams) — it's simpler to run (plain HTTP, no `upgrade`), and `EventSource` **reconnects on its own**, so there's no client backoff to write.
+
+## Minimal SSE endpoint (no framework)
+
+A function's default export is `{ fetch }`; SSE needs nothing more. Return a `ReadableStream` and write `data:` frames into it:
+
+```typescript
+// src/index.ts
+const encoder = new TextEncoder();
+
+export default {
+  fetch(request: Request): Response {
+    const url = new URL(request.url);
+    if (url.pathname !== "/events") return new Response("ok");
+
+    const stream = new ReadableStream<Uint8Array>({
+      start(controller) {
+        // An SSE frame is `data: <payload>\n\n`. A line starting with `:` is a
+        // comment — used here as a heartbeat to keep the stream from going idle.
+        controller.enqueue(encoder.encode("data: hello\n\n"));
+        const timer = setInterval(
+          () => controller.enqueue(encoder.encode(": ping\n\n")),
+          25_000,
+        );
+        // cancel() fires when the client disconnects.
+        return () => clearInterval(timer);
+      },
+    });
+
+    return new Response(stream, {
+      headers: {
+        "Content-Type": "text/event-stream",
+        "Cache-Control": "no-cache, no-transform",
+        Connection: "keep-alive",
+      },
+    });
+  },
+};
+```
+
+> `cancel()` is returned from `start()` here for brevity; you can also declare it as a separate `cancel()` method on the stream's underlying source. Either way, use it to drop the client from any broadcast set and clear timers.
+
+## With Hono
+
+Hono routes the HTTP side; the SSE response is the same `ReadableStream`. Returning a raw `Response` keeps full control over the stream (and sidesteps concurrent-write edge cases in stream helpers):
+
+```typescript
+// src/index.ts
+import { Hono } from "hono";
+import { cors } from "hono/cors";
+
+const app = new Hono();
+app.use("*", cors({ origin: process.env.WEB_ORIGIN ?? "*" })); // EventSource is cross-origin from a SPA
+
+app.get("/events", (c) => {
+  const stream = new ReadableStream<Uint8Array>({
+    start(controller) {
+      controller.enqueue(new TextEncoder().encode("data: connected\n\n"));
+      // ...register `controller` in a broadcast set; see fan-out below.
+    },
+  });
+  return new Response(stream, {
+    headers: { "Content-Type": "text/event-stream", "Cache-Control": "no-cache, no-transform" },
+  });
+});
+
+export default app;
+```
+
+## Push to every client, across isolates
+
+The fan-out rule is identical to WebSockets ([Fan-out across isolates](../SKILL.md#fan-out-across-isolates-do-not-skip-this)): each isolate keeps its **own** set of open streams, so broadcasting in-process only reaches the clients on that isolate. Hold a `Set` of stream controllers, and fan out across isolates with Postgres `LISTEN`/`NOTIFY`. Keep the source-of-truth state in Postgres — module state doesn't survive eviction.
+
+```typescript
+import { Pool, Client } from "pg";
+
+const encoder = new TextEncoder();
+const clients = new Set<ReadableStreamDefaultController<Uint8Array>>();
+const pool = new Pool({ connectionString: process.env.DATABASE_URL, max: 5 });
+const CHANNEL = "events";
+
+// One dedicated DIRECT connection per isolate to receive events (LISTEN needs a
+// real session — use DATABASE_URL_UNPOOLED, not the pooled URL).
+const listener = new Client({ connectionString: process.env.DATABASE_URL_UNPOOLED });
+listener.connect().then(() => listener.query(`LISTEN ${CHANNEL}`));
+listener.on("notification", (msg) => {
+  if (!msg.payload) return;
+  const frame = encoder.encode(`data: ${msg.payload}\n\n`);
+  for (const controller of clients) {
+    try {
+      controller.enqueue(frame); // enqueue is synchronous — no concurrent-await hazard
+    } catch {
+      clients.delete(controller); // controller already closed
+    }
+  }
+});
+
+// Anywhere you mutate state, NOTIFY so every isolate pushes to its own streams.
+function publish(payload: unknown) {
+  return pool.query("SELECT pg_notify($1, $2)", [CHANNEL, JSON.stringify(payload)]);
+}
+```
+
+Register/unregister each connection in `clients` from the stream's `start`/`cancel`, and add a module-scope heartbeat (`setInterval`, every ~25–30s) that enqueues `: ping\n\n` to every controller so idle streams stay alive (see [Caveats](#caveats)).
+
+## Wire format (just text)
+
+Each event is newline-delimited fields ending in a blank line:
+
+```
+data: a one-line payload\n\n
+event: count\ndata: 42\n\n          # named event → addEventListener("count", …)
+id: 7\ndata: resumable\n\n            # sets EventSource.lastEventId for resume
+: this is a comment / heartbeat\n\n   # ignored by the client; keeps the stream warm
+retry: 5000\n\n                       # tells the client how long to wait before reconnecting
+```
+
+Send `data:` with no `event:` field to deliver the default `message` event, which the client reads with `EventSource.onmessage` (no `addEventListener` needed).
+
+## Client
+
+```typescript
+const source = new EventSource(`${FUNCTION_URL}/events`); // GET only
+source.onmessage = (e) => console.log("update", e.data);  // default "message" events
+source.onerror = () => {/* EventSource auto-reconnects; nothing to do */};
+// source.close() to stop.
+```
+
+`EventSource` **reconnects automatically** with the server's `retry:` interval, replaying `Last-Event-ID` if you set `id:` — so unlike WebSockets you don't write a reconnect loop. Its constraints: it's **GET-only and can't set request headers**, so authenticate the same way as a [WebSocket](../SKILL.md#websocket-servers) — a `?token=` query param (verify with `jwtVerify` before streaming) or a cookie. (Use the modern `eventsource` polyfill if you need `Authorization` headers.)
+
+## Caveats
+
+- **Heartbeat or it dies.** Streams stay open only while bytes flow — Neon's window is 15 min ([Timeouts](../SKILL.md#timeouts-and-runtime-limits)), but intermediary proxies are usually far stricter (tens of seconds). Emit a `: ping\n\n` comment every ~25–30s so the stream never goes quiet.
+- **`no-transform`.** Set `Cache-Control: no-cache, no-transform` so proxies don't buffer or rewrite the stream.
+- **Enqueue is synchronous.** `controller.enqueue()` doesn't return a promise, so broadcasting from the `LISTEN` handler can't interleave awaits mid-write — wrap each in `try/catch` and drop dead controllers.
+- **CORS.** A SPA hits the function cross-origin, so set `Access-Control-Allow-Origin`. `EventSource` sends no credentials by default, so `*` is fine for public streams.
+- **One-way only.** SSE is server → client. For client → server, the browser makes normal `fetch`/`POST` calls (often to the same function); reach for [WebSockets](../SKILL.md#websocket-servers) only when you need bidirectional, low-latency frames.
+
+Together — a Hono `fetch` SSE endpoint, `LISTEN`/`NOTIFY` fan-out, heartbeat, a counter persisted in Postgres, and a client-only TanStack Router SPA consuming it with `EventSource` — these compose into a complete realtime backend on a single function.

package/bundled-skills/neon-object-storage/SKILL.md

@@ -0,0 +1,200 @@
+---
+name: neon-object-storage
+description: S3-compatible object storage that branches with your Neon project, so files and the database stay in sync across every branch. Use when a user wants object storage, a bucket, blob/file storage, or somewhere to put uploads, images, documents, avatars, or user-generated files for their...
+risk: unknown
+source: https://github.com/neondatabase/agent-skills/tree/main/skills/neon-object-storage
+source_repo: neondatabase/agent-skills
+source_type: official
+date_added: 2026-07-01
+license: Apache-2.0
+license_source: https://github.com/neondatabase/agent-skills/blob/main/LICENSE
+---
+
+# Neon Object Storage
+
+This is a preview feature and only available in `us-east-2`. Neon Object Storage is S3-compatible object storage that branches with your projects: every branch gets its own isolated storage state, so files and database rows stay in sync across dev, preview, staging, and production.
+
+Use this skill to help the user store and serve files that branch alongside their database. Deliver a working bucket and upload/download flow, a branch-aware S3 client wired to the injected env vars, or a precise answer from the official Neon docs.
+
+## When to Use
+
+Reach for Neon Object Storage when the user needs to store files (images, uploads, generated assets, documents, backups) and any of the following are true:
+
+- **They already use Neon Postgres and don't want a second provider.** One backend, one bill, one CLI, one set of branches — instead of standing up and wiring a separate AWS S3 / R2 / Supabase Storage account. The same Neon credential that backs the database backs storage.
+- **Files must stay in sync with the database across environments.** Storage branches _together with_ your Postgres data. Fork a branch and the child instantly inherits the parent's buckets and objects at that point in time — copy-on-write, so no data is duplicated. This is what makes agent, dev, preview, and test environments seamless: a preview branch gets a consistent snapshot of _both_ the rows and the files they reference, and writes on the child never touch the parent.
+- **They want safe, throwaway environments.** Upload, overwrite, and delete files in a preview/CI branch without any risk to production data, then drop the branch.
+- **They want standard S3 tooling.** It's built on S3 semantics and speaks the S3 API, so the AWS SDKs, `boto3`, the AWS CLI, and presigned URLs all work — reliable and familiar, with no proprietary client.
+
+If the user has no Neon project, isn't on Postgres, and just needs a standalone CDN-backed asset store, a dedicated object store may fit better — but the moment branch-consistent files + rows matter, this is the reason to use it.
+
+## What It Does
+
+- **S3-compatible** — Works with existing S3 SDKs, `boto3`, the AWS CLI, and presigned URLs. Path-style addressing and SigV4 only.
+- **Branches with your database** — Every Neon branch gets its own isolated, copy-on-write storage state. Forking copies no data.
+- **Two access modes** — `private` buckets require a credential for every operation; `public_read` buckets allow anonymous reads with authenticated writes.
+- **One credential system** — The same Neon credential system used by Functions and the AI Gateway.
+
+## Setup
+
+Object storage is part of the `neon.ts` infrastructure-as-code config (see the `neon` skill for the branch-first workflow, `link`/`checkout`, and `neon.ts` basics). Declare buckets under `preview.buckets`, keyed by bucket name:
+
+```typescript
+// neon.ts
+import { defineConfig } from "@neon/config/v1";
+
+export default defineConfig({
+  preview: {
+    buckets: {
+      images: {}, // private by default
+      "public-assets": { access: "public_read" },
+    },
+  },
+});
+```
+
+Provision the declared buckets on the linked branch:
+
+```bash
+neon deploy   # alias for `neon config apply`
+```
+
+## Neon Infrastructure as Code (`neon.ts`)
+
+The `preview.buckets` block above is part of `neon.ts`, Neon's infrastructure-as-code file — one TypeScript file declares your buckets alongside every other service the branch should have (see the `neon` skill for the full reference). Reconcile the declaration against a branch the Terraform way:
+
+```bash
+neon config status   # print the branch's live config (which buckets exist)
+neon config plan     # dry-run diff of what apply would change
+neon config apply    # create the declared buckets  (neon deploy is an alias)
+```
+
+Buckets are **branch-scoped**: when a `neon.ts` is present, `neon checkout` applies the policy as it _creates_ a branch, so a fresh preview/CI branch comes up with its buckets already provisioned (and copy-on-write objects inherited from the parent). Checking out an _existing_ branch doesn't reconcile it — run `neon deploy` to apply changes. Provisioning (`config apply` / `deploy`), `link`, and `checkout` also pull the branch's S3 credentials into your local `.env.local`, so the same `env pull` step shown below happens for you on those commands.
+
+For typed, validated access to the injected S3 credentials, pass the same config object to `parseEnv` from `@neon/env` — it returns an `env.storage` namespace (`accessKeyId`, `secretAccessKey`, `endpoint`, `region`) derived from your `neon.ts`.
+
+## Environment variables
+
+When `preview.buckets` is declared, Neon injects **AWS-standard** S3 env vars so the AWS SDKs work from the environment with zero extra config. Inside a deployed Neon Function these are injected automatically; locally, pull them onto disk (or inject them at runtime) via the CLI:
+
+```bash
+neon env pull            # writes the branch's vars into .env (or .env.local)
+# or, without writing a file, inject at runtime:
+neon-env run -- <your dev command>
+```
+
+| Variable                | Meaning                                             |
+| ----------------------- | --------------------------------------------------- |
+| `AWS_ACCESS_KEY_ID`     | S3 Access Key ID (the branch credential's token id) |
+| `AWS_SECRET_ACCESS_KEY` | S3 Secret Access Key                                |
+| `AWS_ENDPOINT_URL_S3`   | Branch S3 endpoint URL                              |
+| `AWS_REGION`            | Region, e.g. `us-east-2`                            |
+
+Because the names are AWS-standard, the AWS SDK picks up the credentials, endpoint, and region from the environment automatically. Credentials are branch-scoped and valid for that branch and all its descendants.
+
+## Working with objects: the Files SDK (recommended)
+
+The simplest, most portable way to read and write objects is the [Files SDK](https://files-sdk.dev) with its `neon` adapter — a small, unified storage API (`upload`, `download`, `url`, `list`, `exists`, `copy`, `delete`, `signedUploadUrl`) over web-standard I/O. It uses the AWS S3 client under the hood, configured appropriately for Neon, and relabels errors as `Neon error` — so there's nothing to misconfigure. Reach for this first.
+
+Install it alongside the AWS S3 peer dependencies the adapter uses internally:
+
+```bash
+npm install files-sdk @aws-sdk/client-s3 @aws-sdk/s3-presigned-post @aws-sdk/s3-request-presigner
+```
+
+The adapter resolves its endpoint, region, and credentials from the same injected `AWS_*` env vars — pass only the bucket name:
+
+```typescript
+import { Files } from "files-sdk";
+import { neon } from "files-sdk/neon";
+
+const files = new Files({ adapter: neon({ bucket: "images" }) });
+
+// Upload — body may be a Buffer, Uint8Array, Blob, File, ReadableStream, or string
+await files.upload("generated/cat.jpg", fileBuffer, { contentType: "image/jpeg" });
+
+// Download
+const file = await files.download("generated/cat.jpg");
+const bytes = new Uint8Array(await file.arrayBuffer());
+
+// Presigned GET — share without exposing credentials (defaults to a 1h expiry)
+const url = await files.url("generated/cat.jpg", { expiresIn: 3600 });
+
+// Plus: files.exists(), files.list({ prefix }), files.copy(), files.delete(), files.signedUploadUrl()
+```
+
+Swap the adapter import (`files-sdk/s3`, `files-sdk/r2`, `files-sdk/gcs`, …) and the rest of your code is unchanged.
+
+## Working with objects: the AWS S3 client (alternative)
+
+Neon speaks the S3 API directly, so you can drop down to the AWS SDK whenever you prefer the native client or already depend on it. The credentials, endpoint, and region are read from the standard AWS env chain, so the only setting you pass is `forcePathStyle: true` — Neon requires path-style addressing, so the S3 client **must** set it:
+
+```typescript
+import { S3Client } from "@aws-sdk/client-s3";
+
+const s3 = new S3Client({
+  forcePathStyle: true, // required: Neon uses path-style addressing
+});
+```
+
+If you prefer typed access instead of reading `process.env` directly, `parseEnv` (from `@neon/env`) returns a validated `env.storage` namespace (`accessKeyId`, `secretAccessKey`, `endpoint`, `region`) derived from your `neon.ts` — see the `neon` skill.
+
+Then upload, download, and presign with the raw command objects:
+
+```typescript
+import { PutObjectCommand, GetObjectCommand } from "@aws-sdk/client-s3";
+import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
+
+const BUCKET = "images";
+
+// Upload
+await s3.send(
+  new PutObjectCommand({
+    Bucket: BUCKET,
+    Key: "generated/cat.jpg",
+    Body: fileBuffer,
+    ContentType: "image/jpeg",
+  }),
+);
+
+// Download
+const res = await s3.send(
+  new GetObjectCommand({ Bucket: BUCKET, Key: "generated/cat.jpg" }),
+);
+const bytes = await res.Body?.transformToByteArray();
+
+// Presigned GET — share without exposing credentials
+const url = await getSignedUrl(
+  s3,
+  new GetObjectCommand({ Bucket: BUCKET, Key: "generated/cat.jpg" }),
+  { expiresIn: 3600 },
+);
+```
+
+The canonical pattern for pairing storage with the database on a branch: an agent generates an image → `PutObject` into the `images` bucket → a row is inserted in Postgres → a presigned URL is returned on read. Store the bucket **key** (not the bytes) in a Postgres column, and presign on read. Because both the row and the object live on the same branch, they branch together and never drift.
+
+`neon` also has first-class bucket/object commands (`neon bucket create|list|delete`, `neon bucket object put|get|list|delete`) for scripting and one-off operations.
+
+## Availability
+
+Neon Object Storage is a preview (early access) feature available only on new projects in the `us-east-2` region. Confirm the user's Neon project is a new project in `us-east-2` before proceeding; it can't be enabled on existing projects. If the user does not yet have access, point them to the private beta sign-up: https://neon.com/blog/were-building-backends#access
+
+## Neon Documentation
+
+The Neon documentation is the source of truth and Object Storage is evolving rapidly, so always verify against the official docs. Any doc page can be fetched as markdown by appending `.md` to the URL or by requesting `Accept: text/markdown`. Find the right page from the docs index (https://neon.com/docs/llms.txt) and the changelog announcements.
+
+## Further reading
+
+- https://neon.com/docs/storage/overview.md
+- https://neon.com/docs/storage/get-started.md
+- https://neon.com/docs/storage/buckets.md
+- https://neon.com/docs/storage/objects.md
+- https://neon.com/docs/storage/authentication.md
+- https://neon.com/docs/storage/s3-compatibility.md
+- https://neon.com/docs/storage/troubleshooting.md
+- https://files-sdk.dev — Files SDK docs (the `neon` adapter)
+
+## Limitations
+
+- Use this skill only when the task clearly matches its upstream product or API scope.
+- Verify commands, API behavior, pricing, quotas, credentials, and deployment effects against current official documentation before making changes.
+- Do not treat generated examples as a substitute for environment-specific tests, security review, or user approval for destructive or costly actions.