@damiangilgonzalez/harness 1.3.7

package/skills/netlify/SKILL.md

@@ -0,0 +1,208 @@
+---
+name: netlify
+description: "Use when deploying or operating a site on Netlify — writing or fixing netlify.toml, authoring Functions or Edge Functions, redirects, rewrites and headers, env vars per deploy context, and shipping via the Netlify CLI. NOT deploying to Vercel (that is `vercel`)."
+tags: [netlify, deployment, serverless-functions, edge-functions, netlify-toml, redirects]
+recommends: [vercel, cloudflare, nextjs, domains-dns, github-actions]
+origin: risco
+---
+
+# Netlify — netlify.toml, Functions, Edge Functions, redirects & the CLI
+
+> The platform-mechanics layer for Netlify: config, function handlers, routing, env
+> contexts, and the deploy CLI. Not framework code, not generic CI.
+
+## What this owns
+
+You own the Netlify adapter/config surface — `netlify.toml`, `netlify/functions/`,
+`netlify/edge-functions/`, `_redirects`, `_headers`, and `netlify <cmd>`. You do **not** own
+the app's routing or data layer (that is `../nextjs/SKILL.md` / a React skill), DNS records
+(`../domains-dns/SKILL.md`), or another platform's config — Vercel is `../vercel/SKILL.md`,
+Cloudflare is `../cloudflare/SKILL.md`. Their config files and function models differ; never
+cross-apply.
+
+## The 5-minute happy path
+
+```bash
+netlify link                 # link the cwd to a site (or `netlify init` to create one)
+# write/edit netlify.toml (see skeleton below)
+netlify dev                  # local emulation: build, functions, redirects, env injection
+netlify deploy --prod        # build + push straight to production
+```
+
+`netlify deploy` with no flag creates a **draft** deploy (preview URL, not live). `--prod`
+publishes. Test with `netlify dev` first — it is the only local runtime that emulates
+redirects and function routing together.
+
+## Where does each piece of config live?
+
+Two rules decide everything below: **`_redirects`/`_headers` files are processed before the
+`netlify.toml` equivalents**, and a function's own `config` export beats dashboard guesses.
+
+| Concern | Put it in | Why |
+| --- | --- | --- |
+| Redirects / rewrites / SPA fallback | `[[redirects]]` in toml **or** `_redirects` file | One source. File rules run first; pick one and stay consistent. |
+| Response headers (CSP, caching) | `[[headers]]` in toml **or** `_headers` file | Same precedence; keep security headers in version control, not the UI. |
+| Build command / publish dir / functions dir | `[build]` in toml | Single declarative source the build picks up; survives UI drift. |
+| A function's URL path | `export const config = { path }` in the function | Co-located with the handler; deterministic, no dashboard mapping. |
+| Edge function path + ordering | `[[edge_functions]]` in toml | Declaration order in toml is deterministic (inline config is not). |
+| Secrets / API keys / per-context vars | dashboard or `netlify env:set` | Never commit secrets — build-time secrets scanning fails the build if it finds one. |
+
+## netlify.toml skeleton
+
+```toml
+[build]
+  command  = "npm run build"
+  publish  = "dist"            # the directory you deploy; relative to base
+  functions = "netlify/functions"
+  [build.environment]
+    NODE_VERSION = "22"
+
+[functions]
+  node_bundler = "esbuild"
+  # included_files = ["data/**"]   # bundle extra files a function reads at runtime
+
+# SPA fallback — note status 200, NOT 301 (see Redirects)
+[[redirects]]
+  from   = "/*"
+  to     = "/index.html"
+  status = 200
+
+[[headers]]
+  for = "/*"
+  [headers.values]
+    X-Frame-Options = "DENY"
+    Content-Security-Policy = "default-src 'self'"
+
+# per-context override: deploy previews build differently
+[context.deploy-preview]
+  command = "npm run build:preview"
+  [context.deploy-preview.environment]
+    SHOW_PREVIEW_BANNER = "true"
+```
+
+Contexts are `production`, `deploy-preview`, `branch-deploy`, and `branch."name"`. Each can
+override `command`, `publish`, `environment`, etc. The full key-by-key reference (every
+`[build]`/`[functions]`/`[[plugins]]` option, all header/redirect fields) lives in
+[references/netlify-toml.md](references/netlify-toml.md) — link there instead of inlining it.
+
+## Functions (Node runtime)
+
+Default directory is `netlify/functions/`. TypeScript files are `.mts`, JS is `.mjs` (ES
+modules). Use the **modern Web-platform handler** — `Request` in, `Response` out — and route
+with a `config` export, not a dashboard mapping.
+
+```typescript
+// netlify/functions/hello.mts
+import type { Config, Context } from "@netlify/functions";
+
+export default async (req: Request, context: Context) => {
+  const name = new URL(req.url).searchParams.get("name") ?? "world";
+  return Response.json({ hello: name });
+};
+
+export const config: Config = { path: "/api/hello" };
+```
+
+Read secrets from the environment; never hardcode them:
+
+```typescript
+const key = Netlify.env.get("RESEND_API_KEY") ?? process.env.RESEND_API_KEY;
+```
+
+Do **not** revive the legacy AWS-Lambda signature in new functions:
+
+```javascript
+// Bad — legacy handler/event/statusCode shape
+exports.handler = async (event) => ({ statusCode: 200, body: "ok" });
+```
+
+```typescript
+// Good — Web-API handler + Config.path
+export default async (req: Request) => new Response("ok");
+export const config: Config = { path: "/ok" };
+```
+
+Scheduled (`config.schedule` cron), background (`-background` suffix), and streaming
+responses are covered in [references/functions.md](references/functions.md).
+
+## Edge Functions (Deno runtime)
+
+Live in `netlify/edge-functions/`, run on Deno at the edge. Declare them in toml so ordering
+is explicit:
+
+```toml
+[[edge_functions]]
+  function = "geo-rewrite"
+  path     = "/*"
+  # excludedPath = "/assets/*"
+```
+
+When **multiple** edge functions match one path, they run **top-to-bottom in declaration
+order** — declaring in `netlify.toml` is deterministic; relying on each function's inline
+`config` for ordering is not. Pick edge functions for latency-sensitive rewrites,
+geolocation, and A/B routing. Avoid them for heavy npm dependencies or Node-only APIs — use a
+regular Function there.
+
+## Redirects & rewrites
+
+```text
+# _redirects (or the [[redirects]] equivalent)
+/api/*   https://api.example.com/:splat   200   # proxy/rewrite: keep the URL, fetch remote
+/old/*   /new/:splat                       301   # permanent redirect (default status)
+/*       /index.html                        200   # SPA fallback
+```
+
+Three things people get wrong:
+
+- **SPA fallback must be `status = 200`**, not 301. 200 *serves* `index.html` at the original
+  URL so the client router can read the path; a 301 changes the URL and breaks deep links.
+- **Proxy/rewrite = `status = 200`** to a remote URL (add `force = true` to override an
+  existing file at that path).
+- **Processing order**: Edge Functions run first, then `_redirects` rules, then `netlify.toml`
+  redirects; within the set the **first matching rule wins** (top-to-bottom). Put specific
+  rules above the `/*` catch-all.
+
+## Env vars & deploy contexts
+
+```bash
+netlify env:set RESEND_API_KEY "xxxx" --context production
+netlify env:set SHOW_BANNER "true" --context deploy-preview
+netlify env:list --context deploy-preview
+netlify env:import .env            # bulk import (do not commit .env)
+```
+
+Variables are scoped to deploy contexts, so a key can differ between production and previews.
+Build-time **secrets scanning** inspects build output; if a value you marked secret leaks into
+the bundle, the build **fails** — fix the leak, don't disable the scan blindly.
+
+## Deploy & local dev
+
+| Command | Use it for |
+| --- | --- |
+| `netlify dev` | Local: build + functions + redirects + env injection. The truth before deploy. |
+| `netlify deploy` | Draft deploy → preview URL, not live. |
+| `netlify deploy --prod` | Build + publish to production. |
+| `netlify deploy --prod --no-build` | Publish an **already-built** dir; skips the build command. |
+| `netlify deploy --skip-functions-cache` | Force re-bundle functions when a stale cache bites. |
+
+`--no-build` is the classic foot-gun: if you didn't actually build (or built into the wrong
+`publish` dir), you ship a stale or empty site. Only use it when the artifact is fresh.
+
+## Anti-patterns
+
+| Anti-pattern | Why it breaks | Do instead |
+| --- | --- | --- |
+| SPA fallback as `status = 301` | URL rewrites; deep-link refresh 404s or loops | `status = 200` to `/index.html` |
+| Hardcoding API keys in a function | Leaks in bundle; secrets scan fails the build | `Netlify.env.get(...)` / `process.env`, set via `netlify env:set` |
+| Legacy `exports.handler = (event) => ({statusCode})` | Old Lambda shape, mismatched runtime expectations | Web-API `export default (req) => Response` + `config.path` |
+| Relying on inline edge `config` for run order | Ordering is non-deterministic across functions | Declare order in `[[edge_functions]]` in toml |
+| `netlify deploy --prod --no-build` without building | Ships stale/empty `publish` dir | Build first, or drop `--no-build` |
+| Pasting Vercel/Cloudflare config into Netlify | Different files & function models; nothing wires up | Use `netlify.toml` + `netlify/functions`; see `../vercel/SKILL.md` for Vercel |
+| `functions` dir in toml ≠ actual folder on disk | Functions silently not bundled → 404 | Make `[build].functions` match `netlify/functions/` exactly |
+| `/*` redirect above a specific rule | Catch-all wins first; specific rule never matches | Order specific rules before the `/*` fallback |
+
+## Verify
+
+Run `scripts/verify.sh [target-dir]` (default cwd). It confirms a `netlify.toml` exists,
+parses, that any SPA fallback is `status = 200`, and that every `[[redirects]]` has both
+`from` and `to`. Read-only; exits 0 on a clean or empty target.

package/skills/netlify/evals/README.md

@@ -0,0 +1,13 @@
+# Evals — netlify
+
+`cases.yaml` holds three groups. `should_trigger` are prompts where this skill must fire
+(including non-obvious symptom phrasings like SPA-refresh 404s and secrets-scan build failures,
+plus a Catalan case). `should_not_trigger` are nearby prompts that belong to a sibling, each
+tagged with the `route_to` id that should win instead. `capability` is an end-to-end scenario
+with a `must_include` rubric.
+
+There is no automated runner here. To evaluate: feed each `should_trigger` / `should_not_trigger`
+prompt to the router and confirm the skill fires (or yields to the named sibling). For the
+`capability` case, have the agent produce the artifact and check the output covers every
+`must_include` bullet. The structural correctness of an emitted `netlify.toml` is separately
+checkable with `../scripts/verify.sh`.

package/skills/netlify/evals/cases.yaml

@@ -0,0 +1,43 @@
+skill: netlify
+
+should_trigger:
+  - prompt: "My React SPA shows 'Page not found' when I refresh a deep link on Netlify."
+    why: "Non-obvious — the symptom is a missing SPA fallback redirect (status 200 to /index.html), a core Netlify routing config concern."
+  - prompt: "Set up a Netlify function at /api/hello that returns JSON."
+    why: "Direct Functions authoring — modern Web-API handler plus config.path routing in netlify/functions/."
+  - prompt: "Write a netlify.toml with different build commands for deploy previews vs production."
+    why: "Deploy-context overrides ([context.deploy-preview] vs [context.production]) live squarely in this skill."
+  - prompt: "Configura el netlify.toml i desplega-ho a producció amb la CLI."
+    why: "Catalan phrasing for writing netlify.toml and shipping with netlify deploy --prod."
+  - prompt: "My Netlify build passes locally but fails because it detected a secret in env."
+    why: "Non-obvious — Netlify build-time secrets scanning; resolution is env-context handling, a platform-mechanics concern."
+  - prompt: "Add an edge function that geolocates the request and rewrites the path."
+    why: "Edge Functions on Deno with [[edge_functions]] declaration and context.geo — Netlify edge surface."
+
+should_not_trigger:
+  - prompt: "Deploy my Next.js app to Vercel with ISR."
+    route_to: vercel
+    why: "Different platform; Vercel config and function model do not map onto Netlify."
+  - prompt: "Set up Cloudflare Workers with Wrangler and KV."
+    route_to: cloudflare
+    why: "Cloudflare Workers/Wrangler is a separate platform with its own config."
+  - prompt: "How do I implement the React Router routes themselves in my app?"
+    route_to: nextjs
+    why: "Application routing code, not the Netlify deploy/redirect config layer."
+  - prompt: "Point my domain's A and MX records at the right hosts."
+    route_to: domains-dns
+    why: "DNS record management, not Netlify build or redirect configuration."
+  - prompt: "Build a GitHub Actions matrix CI pipeline for tests."
+    route_to: github-actions
+    why: "Generic CI unrelated to Netlify's own build system."
+
+capability:
+  - scenario: "A Vite SPA with a contact form needs: SPA fallback so deep links work, a /api/contact serverless function that emails via an env-stored API key, and a deploy-preview-only banner via a context env var. Produce the netlify.toml plus the function."
+    must_include:
+      - "SPA redirect with status = 200 to /index.html (not 301)"
+      - "netlify/functions handler using Request/Response with export const config { path }"
+      - "import type from @netlify/functions"
+      - "API key read via Netlify.env.get or process.env, not hardcoded"
+      - "[context.deploy-preview] environment override for the banner var"
+      - "netlify deploy --prod mentioned as the ship step"
+      - "explicit note that the secret is set via netlify env:set / not committed"

package/skills/netlify/references/functions.md

@@ -0,0 +1,97 @@
+# Functions & Edge Functions — deeper dimensions
+
+Covers what the SKILL body offloads: scheduled, background, streaming functions, and the
+Node-vs-Deno runtime split. Base directory is `netlify/functions/` (Node) and
+`netlify/edge-functions/` (Deno edge).
+
+## The context object
+
+```typescript
+import type { Config, Context } from "@netlify/functions";
+
+export default async (req: Request, context: Context) => {
+  context.geo;        // { city, country: { code, name }, subdivision, ... }
+  context.cookies;    // get / set / delete cookies
+  context.params;     // matched path params from config.path patterns
+  context.ip;         // client IP
+  return Response.json({ city: context.geo?.city });
+};
+```
+
+## Scheduled functions (cron)
+
+Add `schedule` to the config — no separate cron service needed.
+
+```typescript
+// netlify/functions/cleanup.mts
+import type { Config } from "@netlify/functions";
+
+export default async () => {
+  // runs on the schedule; no request to respond to
+  return new Response("done");
+};
+
+export const config: Config = { schedule: "@hourly" }; // or "0 5 * * *"
+```
+
+Scheduled functions get no live HTTP route; they fire on the cron expression.
+
+## Background functions
+
+Suffix the filename with `-background` (e.g. `process-background.mts`). The HTTP call returns
+**202 immediately** and the function keeps running asynchronously (longer execution budget).
+Use for work the caller shouldn't wait on — webhooks fan-out, image processing, emails.
+
+```typescript
+// netlify/functions/notify-background.mts
+export default async (req: Request) => {
+  // long async work; the response is already 202 to the caller
+  await doSlowWork(await req.json());
+};
+```
+
+## Streaming / SSE responses
+
+Return a `ReadableStream` body to stream incrementally (LLM tokens, SSE, large payloads).
+
+```typescript
+export default async () => {
+  const stream = new ReadableStream({
+    start(controller) {
+      controller.enqueue(new TextEncoder().encode("data: hello\n\n"));
+      controller.close();
+    },
+  });
+  return new Response(stream, {
+    headers: { "content-type": "text/event-stream" },
+  });
+};
+```
+
+## Node (Functions) vs Deno (Edge Functions)
+
+| Dimension | Functions (Node) | Edge Functions (Deno) |
+| --- | --- | --- |
+| Runtime | Node, AWS-Lambda-backed | Deno at the CDN edge |
+| Directory | `netlify/functions/` | `netlify/edge-functions/` |
+| Files | `.mts` / `.mjs` | `.ts` / `.js` |
+| Env access | `process.env` and `Netlify.env.get` | `Netlify.env.get` (no `process`) |
+| npm deps | full npm + native modules | limited; prefer URL/std imports, no native modules |
+| Best for | DB calls, heavy logic, scheduled/background work | rewrites, geolocation, auth gating, A/B at low latency |
+| Routing | `export const config = { path }` | `[[edge_functions]]` in netlify.toml (deterministic order) |
+
+Rule of thumb: reach for an Edge Function only when latency or per-request rewriting matters
+and the dependency footprint is light. Anything that wants the Node ecosystem or runs on a
+schedule belongs in a regular Function.
+
+## Reading env safely
+
+```typescript
+// Node function
+const key = process.env.STRIPE_SECRET ?? Netlify.env.get("STRIPE_SECRET");
+// Edge function
+const key = Netlify.env.get("STRIPE_SECRET");
+```
+
+Set values with `netlify env:set NAME value --context production`. Never hardcode — the
+build's secrets scanner fails on leaked secret values in the bundle.

package/skills/netlify/references/netlify-toml.md

@@ -0,0 +1,115 @@
+# netlify.toml — full annotated reference
+
+Source of truth: `netlify.toml` at the repo root (or under `base` if set). All tables are
+optional; the dashboard fills gaps but the toml wins for keys it declares.
+
+## [build]
+
+```toml
+[build]
+  base      = "frontend"            # subdir to cd into before building (monorepo root)
+  command   = "npm run build"       # the build command
+  publish   = "dist"                # dir to deploy; relative to base
+  functions = "netlify/functions"   # Functions source dir
+  edge_functions = "netlify/edge-functions"
+  [build.environment]
+    NODE_VERSION = "22"             # also: NPM_FLAGS, PYTHON_VERSION, etc.
+```
+
+`base` shifts the working directory; `publish` and `functions` are then relative to it. Get
+this wrong in a monorepo and the build can't find your output.
+
+## [functions]
+
+```toml
+[functions]
+  node_bundler          = "esbuild"          # default modern bundler
+  included_files        = ["data/**", "!data/secret.json"]  # extra files to bundle (globs)
+  external_node_modules = ["sharp"]          # leave these unbundled (native deps)
+  # per-function overrides:
+  [functions."heavy-job"]
+    included_files = ["templates/**"]
+```
+
+`included_files` is how a function reads a file at runtime — by default only the handler and
+its imports are bundled. Native modules that break under esbuild go in `external_node_modules`.
+
+## [[redirects]]
+
+```toml
+[[redirects]]
+  from   = "/old/*"
+  to     = "/new/:splat"
+  status = 301            # default 301 if omitted
+  force  = false          # true = override an existing file at `from`
+  query  = { id = ":id" } # match/forward query params
+  conditions = { Role = ["admin"], Country = ["US"] }
+  [redirects.headers]
+    X-From = "redirect"
+  signed = "API_SIGNATURE_TOKEN"  # for signed proxy redirects
+```
+
+Fields: `from`, `to`, `status`, `force`, `query`, `conditions`, `headers`, `signed`. SPA
+fallback is `from="/*" to="/index.html" status=200`. Proxy/rewrite is `status=200` to a
+remote URL. First matching rule wins, top-to-bottom; `_redirects` file rules run before these.
+
+## [[headers]]
+
+```toml
+[[headers]]
+  for = "/*"
+  [headers.values]
+    Content-Security-Policy = "default-src 'self'; script-src 'self'"
+    X-Frame-Options         = "DENY"
+    X-Content-Type-Options  = "nosniff"
+    Referrer-Policy         = "strict-origin-when-cross-origin"
+    # cache static assets aggressively under a hashed path
+  [[headers]]
+    for = "/assets/*"
+    [headers.values]
+      Cache-Control = "public, max-age=31536000, immutable"
+```
+
+`_headers` file rules are processed before these.
+
+## [[edge_functions]]
+
+```toml
+[[edge_functions]]
+  function     = "geo-rewrite"   # filename (no ext) in netlify/edge-functions/
+  path         = "/*"            # URLPattern
+  excludedPath = "/assets/*"     # carve-outs
+```
+
+Multiple matches on one path run in declaration order, top-to-bottom — the deterministic
+reason to declare here rather than via inline `config`.
+
+## [context.*]
+
+```toml
+[context.production]
+  command = "npm run build"
+[context.deploy-preview]
+  command = "npm run build:preview"
+  [context.deploy-preview.environment]
+    SHOW_PREVIEW_BANNER = "true"
+[context.branch-deploy]
+  command = "npm run build:staging"
+[context."release"]            # a specific branch named "release"
+  command = "npm run build:release"
+```
+
+Any `[build]` key (command, publish, environment, edge_functions, …) can be overridden per
+context. Contexts: `production`, `deploy-preview`, `branch-deploy`, `branch."name"`.
+
+## [[plugins]]
+
+```toml
+[[plugins]]
+  package = "@netlify/plugin-lighthouse"
+  [plugins.inputs]
+    output_path = "reports/lighthouse.html"
+```
+
+Build plugins run at build time around the build command. Install the package (or use a
+UI-installed plugin) and configure inputs here.

package/skills/netlify/scripts/verify.sh

@@ -0,0 +1,95 @@
+#!/usr/bin/env bash
+# verify.sh — read-only sanity check for a Netlify config artifact.
+# Usage: verify.sh [TARGET_DIR]   (default: current directory)
+# Exits 0 on a clean OR empty target (no netlify.toml => nothing to check, not a failure).
+# Exits 1 only when a netlify.toml is present AND structurally wrong.
+
+set -uo pipefail
+
+TARGET="${1:-.}"
+TOML="$TARGET/netlify.toml"
+fail=0
+
+pass() { printf 'PASS: %s\n' "$1"; }
+warn() { printf 'WARN: %s\n' "$1"; }
+bad()  { printf 'FAIL: %s\n' "$1"; fail=1; }
+
+if [ ! -f "$TOML" ]; then
+  echo "INFO: no netlify.toml in '$TARGET' — nothing to verify."
+  exit 0
+fi
+pass "found $TOML"
+
+# 1. Does it parse as TOML?
+if command -v python3 >/dev/null 2>&1; then
+  if python3 - "$TOML" <<'PY' 2>/dev/null
+import sys
+try:
+    import tomllib
+except ModuleNotFoundError:
+    sys.exit(42)  # signal "no tomllib" -> skip, not fail
+with open(sys.argv[1], "rb") as f:
+    tomllib.load(f)
+PY
+  then
+    pass "netlify.toml parses as valid TOML"
+  else
+    rc=$?
+    if [ "$rc" = "42" ]; then
+      warn "python3 has no tomllib (Python < 3.11) — skipping parse check"
+    else
+      bad "netlify.toml does not parse as valid TOML"
+    fi
+  fi
+else
+  warn "python3 not found — skipping TOML parse check"
+fi
+
+# 2. SPA fallback (to "/index.html") must be status = 200, not a 3xx.
+#    Scan each [[redirects]] block; if its `to` is /index.html, its status must be 200.
+if command -v python3 >/dev/null 2>&1 && python3 -c "import tomllib" >/dev/null 2>&1; then
+  python3 - "$TOML" <<'PY'
+import sys, tomllib
+with open(sys.argv[1], "rb") as f:
+    data = tomllib.load(f)
+reds = data.get("redirects", [])
+ok = True
+for r in reds:
+    if "from" not in r or "to" not in r:
+        print("FAIL: a [[redirects]] block is missing 'from' or 'to'")
+        ok = False
+    if r.get("to") == "/index.html" and r.get("status", 301) != 200:
+        print("FAIL: SPA fallback (to=/index.html) must be status = 200, not %r" % r.get("status", 301))
+        ok = False
+if "build" not in data:
+    print("WARN: no [build] table — builds will rely on dashboard settings")
+if ok:
+    print("PASS: redirects have from+to and any SPA fallback is status 200")
+sys.exit(0 if ok else 1)
+PY
+  [ $? -ne 0 ] && fail=1
+else
+  # Fallback grep-based check when tomllib is unavailable.
+  if grep -Eq 'to[[:space:]]*=[[:space:]]*"/index\.html"' "$TOML"; then
+    # crude: ensure a status 200 appears near a /index.html target
+    if grep -Eq 'status[[:space:]]*=[[:space:]]*200' "$TOML"; then
+      pass "SPA fallback target present and a status = 200 is declared"
+    else
+      bad "SPA fallback to /index.html found but no status = 200 declared"
+    fi
+  fi
+fi
+
+# 3. Optional: if the netlify CLI is installed, surface its parse via build --dry (best-effort).
+if command -v netlify >/dev/null 2>&1; then
+  pass "netlify CLI available (run 'netlify build --dry' for a deeper check)"
+else
+  warn "netlify CLI not installed — CLI-level checks skipped"
+fi
+
+if [ "$fail" -ne 0 ]; then
+  echo "RESULT: FAIL"
+  exit 1
+fi
+echo "RESULT: PASS"
+exit 0