@netlify/agent-runner-cli 1.66.0 → 1.67.0-alpha.1

package/dist/skills/netlify-forms/SKILL.md

@@ -0,0 +1,304 @@
+---
+name: netlify-forms
+description: Build and configure Netlify Forms for serverless form handling. Use when implementing contact forms, feedback forms, file uploads, or any form that collects user submissions without backend code.
+---
+
+# Netlify Forms
+
+Netlify Forms is a serverless form-handling service. The build system parses HTML at deploy time to detect forms and
+automatically creates submission endpoints.
+
+## Quick Start
+
+Add `data-netlify="true"` or `netlify` attribute to any `<form>` tag:
+
+```html
+<form name="contact" method="POST" data-netlify="true">
+  <input type="text" name="name" required />
+  <input type="email" name="email" required />
+  <textarea name="message"></textarea>
+  <button type="submit">Send</button>
+</form>
+```
+
+**Key requirements:**
+
+- The `name` attribute identifies the form in Netlify UI (must be unique per site)
+- Method must be `POST`
+- Netlify injects a hidden `form-name` field during build
+
+## AJAX / JavaScript Submission
+
+Submit forms without page reload:
+
+```javascript
+const form = document.getElementById('contact-form')
+
+form.addEventListener('submit', async (e) => {
+  e.preventDefault()
+
+  const response = await fetch('/', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+    body: new URLSearchParams(new FormData(form)).toString(),
+  })
+
+  if (response.ok) {
+    // Handle success
+  }
+})
+```
+
+**Critical AJAX requirements:**
+
+1. Content-Type MUST be `application/x-www-form-urlencoded`
+2. Include hidden `form-name` field in your HTML:
+   ```html
+   <input type="hidden" name="form-name" value="contact" />
+   ```
+
+## JavaScript Frameworks (React, Vue, Next.js)
+
+Netlify's build bot cannot detect forms rendered client-side. You MUST create a static HTML version.
+
+### Next.js Runtime v5
+
+If using Netlify Forms with Next.js Runtime v5, you **must**:
+
+1. Extract form definitions to a dedicated static HTML file (e.g., `public/__forms.html`)
+2. Submit forms using AJAX — full-page navigation won't work
+
+### Solution: Hidden HTML Skeleton
+
+Create `public/__forms.html` (or include in your static HTML):
+
+```html
+<!-- This file is only for Netlify's build bot detection -->
+<form name="contact" netlify hidden>
+  <input name="name" />
+  <input name="email" />
+  <textarea name="message"></textarea>
+</form>
+```
+
+### React Example
+
+```jsx
+function ContactForm() {
+  const handleSubmit = async (e) => {
+    e.preventDefault()
+    const formData = new FormData(e.target)
+
+    await fetch('/', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+      body: new URLSearchParams(formData).toString(),
+    })
+  }
+
+  return (
+    <form name="contact" method="POST" onSubmit={handleSubmit}>
+      {/* Hidden field required for AJAX */}
+      <input type="hidden" name="form-name" value="contact" />
+      <input name="name" required />
+      <input name="email" type="email" required />
+      <textarea name="message" />
+      <button type="submit">Send</button>
+    </form>
+  )
+}
+```
+
+## File Uploads
+
+```html
+<form name="upload" method="POST" data-netlify="true" enctype="multipart/form-data">
+  <input type="file" name="attachment" />
+  <button type="submit">Upload</button>
+</form>
+```
+
+**Limits:**
+
+- Maximum request size: **8 MB**
+- Timeout: **30 seconds**
+- One file per input field (use multiple inputs for multiple files)
+
+**Security:** For file uploads containing PII (personally identifiable information), use the
+[Very Good Security (VGS)](https://www.netlify.com/integrations/very-good-security/) integration for additional
+protection.
+
+**AJAX file uploads:** Do NOT set Content-Type header - let browser set `multipart/form-data` with boundary:
+
+```javascript
+// Correct - no Content-Type header
+fetch('/', {
+  method: 'POST',
+  body: new FormData(form), // Browser sets correct Content-Type
+})
+```
+
+## Spam Protection
+
+### Honeypot Field (Recommended)
+
+```html
+<form name="contact" method="POST" data-netlify="true" netlify-honeypot="bot-field">
+  <!-- Hidden from humans, filled by bots -->
+  <p style="display:none">
+    <label>Don't fill this: <input name="bot-field" /></label>
+  </p>
+
+  <!-- Visible fields -->
+  <input name="name" required />
+  <button type="submit">Send</button>
+</form>
+```
+
+### reCAPTCHA v2 (Netlify-provided)
+
+```html
+<form name="contact" method="POST" data-netlify="true" data-netlify-recaptcha="true">
+  <input name="name" required />
+
+  <!-- Netlify injects reCAPTCHA here -->
+  <div data-netlify-recaptcha="true"></div>
+
+  <button type="submit">Send</button>
+</form>
+```
+
+Only one Netlify-provided reCAPTCHA per page. For multiple CAPTCHAs on one page, use custom reCAPTCHA.
+
+### Custom reCAPTCHA v2
+
+Use your own reCAPTCHA 2 code with Netlify validation:
+
+1. Sign up for a [reCAPTCHA API key pair](http://www.google.com/recaptcha/admin) and add the reCAPTCHA script/widget to
+   your form.
+2. Set environment variables in Netlify (UI, CLI, or API):
+   - `SITE_RECAPTCHA_KEY` — your reCAPTCHA site key (scopes: Builds + Runtime)
+   - `SITE_RECAPTCHA_SECRET` — your reCAPTCHA secret key (scope: Runtime)
+3. Add `data-netlify-recaptcha="true"` to your `<form>` tag.
+
+Netlify validates the `g-recaptcha-response` server-side on each submission.
+
+**For AJAX with reCAPTCHA:** Include `g-recaptcha-response` in POST body (automatic if using `FormData()`).
+
+## Success Redirects
+
+```html
+<!-- Redirect to custom thank-you page -->
+<form name="contact" method="POST" data-netlify="true" action="/thank-you"></form>
+```
+
+The `action` path must:
+
+- Start with `/`
+- Be relative to site root
+- Point to an existing page
+
+## Notifications
+
+### Email Notifications
+
+Configure in Netlify UI: **Project configuration > Notifications > Emails and webhooks > Form submission notifications**
+
+- Include `<input name="email">` to set reply-to address automatically
+- Custom subject line:
+  ```html
+  <input type="hidden" name="subject" value="New inquiry from %{formName}" />
+  ```
+- Available variables: `%{formName}`, `%{siteName}`, `%{submissionId}`
+- For forms created before May 5, 2023: remove `[Netlify]` prefix from subject by adding `data-remove-prefix`:
+  ```html
+  <input type="hidden" name="subject" data-remove-prefix value="Sales inquiry" />
+  ```
+
+### Webhooks
+
+Configure in Netlify UI: **Project configuration > Notifications > Emails and webhooks > Form submission notifications**
+
+Sends JSON payload on each verified submission.
+
+## Function Triggers
+
+Trigger serverless functions on submissions:
+
+```typescript
+// netlify/functions/submission-created.mts
+import type { Context } from '@netlify/functions'
+
+interface FormPayload {
+  form_name: string
+  data: Record<string, string>
+  created_at: string
+}
+
+export default async (req: Request, context: Context) => {
+  const { payload } = (await req.json()) as { payload: FormPayload }
+
+  console.log('Form:', payload.form_name)
+  console.log('Data:', payload.data)
+
+  // Process submission (send to CRM, Slack, etc.)
+
+  return new Response('OK')
+}
+```
+
+**Event name:** `submission-created` (filename must match)
+
+## Limits
+
+| Feature      | Free Tier   | Paid Tier  |
+| ------------ | ----------- | ---------- |
+| Submissions  | 100/month   | Metered    |
+| File Storage | 10 MB/month | Scalable   |
+| Request Size | 8 MB        | 8 MB       |
+| Timeout      | 30 seconds  | 30 seconds |
+
+## Common Errors & Solutions
+
+### "404 on submit"
+
+**Cause:** Build bot didn't detect the form. **Fix:**
+
+1. Ensure static HTML version exists for JS frameworks
+2. Verify `form-name` hidden input is present
+3. Check form has `name` attribute
+
+### Submissions not appearing
+
+**Check:**
+
+1. Look in **Spam** folder in Netlify UI (Akismet filtering)
+2. Avoid test values like "test@test.com" or "asdf" — use real email and full sentences
+3. Verify form was included in the latest deploy
+
+### AJAX submission fails silently
+
+**Ensure:**
+
+1. Content-Type is `application/x-www-form-urlencoded` (not JSON)
+2. `form-name` field is included in body
+3. Check browser Network tab for actual response
+
+### File upload fails
+
+**Check:**
+
+1. Total request size under 8 MB
+2. Not setting Content-Type header manually
+3. Using `enctype="multipart/form-data"` on form
+
+## API Access
+
+List submissions programmatically:
+
+```bash
+curl -H "Authorization: Bearer $NETLIFY_AUTH_TOKEN" \
+  https://api.netlify.com/api/v1/forms/{form_id}/submissions
+```
+
+Export available as CSV from Netlify UI.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@netlify/agent-runner-cli",
   "type": "module",
-  "version": "1.66.0",
+  "version": "1.67.0-alpha.1",
   "description": "CLI tool for running Netlify agents",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -13,6 +13,7 @@
   "files": [
     "dist/**/*.js",
     "dist/**/*.d.ts",
+    "dist/skills/**",
     "patches",
     "scripts"
   ],
@@ -43,7 +44,7 @@
   },
   "config": {
     "eslint": "--cache --format=codeframe --max-warnings=0 \"{src,scripts,test,.github}/**/*.{js,ts,md,html}\"",
-    "prettier": "--ignore-path .gitignore --loglevel=warn \"{src,scripts,test,.github}/**/*.{js,ts,md,yml,json,html}\" \"*.{js,ts,yml,json,html}\" \".*.{js,ts,yml,json,html}\" \"!**/package-lock.json\" \"!package-lock.json\""
+    "prettier": "--ignore-path .gitignore --loglevel=warn \"{src,scripts,test,.github}/**/*.{js,ts,md,yml,json,html}\" \"*.{js,ts,yml,json,html}\" \".*.{js,ts,yml,json,html}\" \"!**/package-lock.json\" \"!package-lock.json\" \"!src/skills/**/*.md\""
   },
   "keywords": [],
   "license": "MIT",
@@ -76,7 +77,7 @@
     "vitest": "^4.0.16"
   },
   "dependencies": {
-    "@anthropic-ai/claude-code": "2.1.32",
+    "@anthropic-ai/claude-code": "2.1.37",
     "@anthropic-ai/sdk": "0.72.1",
     "@google/gemini-cli": "0.25.2",
     "@netlify/otel": "^5.1.1",