Update actions to use destructured data and error object from actions call, add Zod types to contact and downloads actions

Author: webstackdev

.github/test/README.md

@@ -10,19 +10,19 @@ It is intended for local debugging of GitHub Actions only. It is not an end-to-e
 Run a single workflow by name (the name is the workflow filename without extension from `.github/workflows/*.yml`):
 
 ```bash
-npm run test:action:runner -- <workflowName>
+npm run debug:action -- <workflowName>
 ```
 
 Example:
 
 ```bash
-npm run test:action:runner -- cron
+npm run debug:action -- cron
 ```
 
 Run all workflows (mostly useful when iterating on the runner itself):
 
 ```bash
-npm run test:action:runner
+npm run debug:action
 ```
 
 ## Events

.github/workflows/playwright.yml

@@ -27,7 +27,8 @@ jobs:
       CONVERTKIT_API_KEY: ${{ vars.CONVERTKIT_API_KEY }}
       CONVERTKIT_HTTP_PORT: ${{ vars.CONVERTKIT_HTTP_PORT }}
       CRON_SECRET: ${{ vars.CRON_SECRET }}
-      DEV_SERVER_HOST: 127.0.0.1
+      # Use localhost so IPv6-only listeners (e.g. ::1) are reachable under act.
+      DEV_SERVER_HOST: localhost
       DEV_SERVER_PORT: ${{ vars.DEV_SERVER_PORT }}
       DISABLE_TELEMETRY: true
       FORCE_COLOR: 3
@@ -58,20 +59,86 @@ jobs:
 
       - name: Start Astro dev server
         run: |
-          npm run dev -- --host 0.0.0.0 --port "${DEV_SERVER_PORT}" > /tmp/astro-dev.log 2>&1 &
+          echo "Starting Astro dev server on ${DEV_SERVER_HOST}:${DEV_SERVER_PORT}"
+
+          build_healthcheck_urls() {
+            echo "http://localhost:${DEV_SERVER_PORT}/"
+            echo "http://127.0.0.1:${DEV_SERVER_PORT}/"
+            echo "http://[::1]:${DEV_SERVER_PORT}/"
+          }
+
+          if [ "${DEBUG:-0}" = "1" ]; then
+            echo "[debug] DEBUG=1"
+            echo "[debug] DEV_SERVER_HOST=${DEV_SERVER_HOST:-<unset>}"
+            echo "[debug] DEV_SERVER_PORT=${DEV_SERVER_PORT:-<unset>}"
+            echo "[debug] node=$(node --version 2>/dev/null || true)"
+            echo "[debug] npm=$(npm --version 2>/dev/null || true)"
+          fi
+
+          nohup npm run dev -- --host 0.0.0.0 --port "${DEV_SERVER_PORT}" > /tmp/astro-dev.log 2>&1 &
           echo $! > /tmp/astro-dev.pid
 
+          sleep 1
+          if ! ps -p "$(cat /tmp/astro-dev.pid)" > /dev/null 2>&1; then
+            echo "❌ Astro dev server process exited immediately"
+            echo '--- Astro dev server log ---'
+            cat /tmp/astro-dev.log || true
+            exit 1
+          fi
+
+          if [ "${DEBUG:-0}" = "1" ]; then
+            echo "[debug] astro pid=$(cat /tmp/astro-dev.pid)"
+            ps -fp "$(cat /tmp/astro-dev.pid)" || true
+            echo "[debug] listening ports (ss -ltnp)"
+            ss -ltnp || true
+            echo "[debug] curl check (verbose)"
+            while read -r url; do
+              echo "[debug] probing ${url}"
+              curl -v "${url}" || true
+            done < <(build_healthcheck_urls)
+            echo "[debug] tail /tmp/astro-dev.log"
+            tail -n 200 /tmp/astro-dev.log || true
+          fi
+
       - name: Wait for Astro dev server
         run: |
-          for i in $(seq 1 60); do
-            if curl -fsS "http://${DEV_SERVER_HOST}:${DEV_SERVER_PORT}/" > /dev/null; then
-              echo "✅ Dev server is responding"
+          build_healthcheck_urls() {
+            echo "http://localhost:${DEV_SERVER_PORT}/"
+            echo "http://127.0.0.1:${DEV_SERVER_PORT}/"
+            echo "http://[::1]:${DEV_SERVER_PORT}/"
+          }
+
+          probe_dev_server() {
+            local url
+            while read -r url; do
+              if curl -fsS "${url}" > /dev/null; then
+                echo "✅ Dev server is responding at ${url}"
+                return 0
+              fi
+            done < <(build_healthcheck_urls)
+            return 1
+          }
+
+          # `npm run dev` runs `astro sync` first; allow time for it to finish.
+          for i in $(seq 1 120); do
+            if probe_dev_server; then
               exit 0
             fi
+
+            if [ "${DEBUG:-0}" = "1" ]; then
+              echo "[debug] still waiting... attempt=${i}/120"
+              if [ -f /tmp/astro-dev.pid ]; then
+                echo "[debug] pid=$(cat /tmp/astro-dev.pid)"
+                ps -fp "$(cat /tmp/astro-dev.pid)" || true
+              fi
+              ss -ltnp || true
+              tail -n 50 /tmp/astro-dev.log || true
+            fi
+
             sleep 1
           done
 
-          echo "❌ Dev server did not start in time"
+          echo "❌ Dev server did not start within 120 seconds"
           echo '--- Astro dev server log ---'
           cat /tmp/astro-dev.log || true
           exit 1

.vscode/settings.json

@@ -59,6 +59,7 @@
     "Linkify",
     "liradb",
     "LNAME",
+    "ltnp",
     "mathbb",
     "Menlo",
     "mlflow",
@@ -72,6 +73,7 @@
     "Neue",
     "Niklas",
     "noabbr",
+    "nohup",
     "Noto",
     "octocat",
     "oden",

_TODO.md

@@ -91,12 +91,6 @@ Google Calendar, Apple Calendar,  Microsoft Outlook and Teams, and generate iCal
 
 See the example image in Social Shares. The social shares UI on mobile should be a modal that slides in from the bottom.
 
-## Uppy file uploads from contact form
-
-docs/CONTACT_FORM.md
-
-Where to upload to?
-
 ## Set up webmentions
 
 Needs to add real API key and test
@@ -106,4 +100,8 @@ Needs to add real API key and test
 - (Optional) Set up Bridgy for social media
 - Test with sample webmentions
 
-python3 .github/test/runner.py cron
+## Uppy file uploads from contact form
+
+docs/CONTACT_FORM.md
+
+Where to upload to?

package.json

@@ -34,6 +34,7 @@
     "containers:down": "FORCE_COLOR=1 docker compose --env-file test/containers/.env -f test/containers/docker-compose.e2e.yml down -v",
     "containers:status": "FORCE_COLOR=1 docker compose --env-file test/containers/.env -f test/containers/docker-compose.e2e.yml ps",
     "containers:logs": "FORCE_COLOR=1 docker compose --env-file test/containers/.env -f test/containers/docker-compose.e2e.yml logs -f",
+    "debug:action": "python3 .github/test/runner.py",
     "dev": "npm run sync && cross-env NODE_ENV=development FORCE_COLOR=1 npx astro dev",
     "dev:env": "FORCE_COLOR=1 dotenv -e .env.development -- npm run dev",
     "dev:env:verbose": "FORCE_COLOR=1 dotenv -e .env.development -- npm run dev -- --verbose",
@@ -53,7 +54,6 @@
     "sync": "FORCE_COLOR=1 npx astro sync",
     "test": "npm run test:unit && npm run test:e2e",
     "test:coverage": "FORCE_COLOR=1 npx vitest run --coverage",
-    "test:action:runner": "python3 .github/test/runner.py",
     "test:e2e": "FORCE_COLOR=1 npx playwright test",
     "test:unit": "npm run test:unit:actions && FORCE_COLOR=1 npx vitest run",
     "test:unit:actions": "FORCE_COLOR=1 python3 -m pytest --import-mode=importlib .github/actions .github/test",

src/actions/contact/@types/index.d.ts

@@ -7,10 +7,12 @@ export type ContactFormData = {
   DataSubjectId?: string
   service?: string
   budget?: string
-  timeline?: string
+  timeline?: ContactTimeline
   website?: string
 }
 
+export type ContactTimeline = 'asap' | '1-month' | '2-3-months' | '3-6-months' | '6-months-plus' | 'flexible'
+
 export type FileAttachment = {
   filename: string
   content: Buffer

src/actions/contact/__tests__/domain.spec.ts

@@ -0,0 +1,30 @@
+import { describe, expect, it } from 'vitest'
+
+import { validateInput } from '../domain'
+
+describe('contact domain validation', () => {
+  it('accepts valid timeline values', () => {
+    const errors = validateInput({
+      name: 'Jane Doe',
+      email: 'jane@example.com',
+      message: 'This is a valid message with enough detail.',
+      timeline: '2-3-months',
+      consent: false,
+    })
+
+    expect(errors).toEqual([])
+  })
+
+  it('rejects invalid timeline values', () => {
+    const errors = validateInput({
+      name: 'Jane Doe',
+      email: 'jane@example.com',
+      message: 'This is a valid message with enough detail.',
+      // @ts-expect-error testing invalid value
+      timeline: 'tomorrow',
+      consent: false,
+    })
+
+    expect(errors).toContain('Invalid project timeline')
+  })
+})

src/actions/contact/action.ts

@@ -1,14 +1,70 @@
 import { Resend } from 'resend'
 import { v4 as uuidv4, validate as uuidValidate } from 'uuid'
 import { ActionError, defineAction } from 'astro:actions'
+import { z } from 'astro/zod'
 import { checkContactRateLimit } from '@actions/utils/rateLimit'
 import { buildRequestFingerprint, createRateLimitIdentifier } from '@actions/utils/requestContext'
 import { getPrivacyPolicyVersion, getResendApiKey, isProd } from '@actions/utils/environment/environmentActions'
 import { ActionsFunctionError, throwActionError } from '@actions/utils/errors'
 import { createConsentRecord } from '@actions/gdpr/domain/consentStore'
-import type { ContactFormData, FileAttachment, EmailData } from '@actions/contact/@types'
-import { generateEmailContent, parseAttachments, validateInput } from './domain'
-import { parseBoolean, readString } from './utils'
+import type { FileAttachment, EmailData } from '@actions/contact/@types'
+import {
+  contactTimelineValues,
+  generateEmailContent,
+  getFormDataFromInput,
+  parseAttachmentsFromInput,
+  validateInput
+} from './domain'
+
+const trimString = (value: unknown): unknown => (typeof value === 'string' ? value.trim() : value)
+
+const emptyStringToUndefined = (value: unknown): unknown => {
+  if (typeof value !== 'string') return value
+  const trimmed = value.trim()
+  return trimmed.length === 0 ? undefined : trimmed
+}
+
+const optionalTrimmedString = (maxLength?: number) => {
+  const base = z.string()
+  const limited = typeof maxLength === 'number' ? base.max(maxLength) : base
+  return z.preprocess(emptyStringToUndefined, limited.optional())
+}
+
+const requiredTrimmedString = (minLength = 1, maxLength?: number) => {
+  const base = z.preprocess(trimString, z.string().min(minLength))
+  return typeof maxLength === 'number' ? base.pipe(z.string().max(maxLength)) : base
+}
+
+const isFile = (value: unknown): value is File => typeof File !== 'undefined' && value instanceof File
+const optionalFile = () => z.custom<File>(isFile).optional()
+
+const contactFormInputSchema = z
+  .object({
+    /** Core fields used by the action. */
+    name: requiredTrimmedString(2, 100),
+    email: z.preprocess(trimString, z.string().email().max(254)),
+    message: requiredTrimmedString(10, 2000),
+    /** Extra fields submitted by the form UI. */
+    company: optionalTrimmedString(100),
+    phone: optionalTrimmedString(50),
+    'project_type': optionalTrimmedString(50),
+    budget: z.preprocess(trimString, z.enum(['5k-10k', '10k-25k', '25k-50k', '50k+'])),
+    timeline: z.preprocess(emptyStringToUndefined, z.enum(contactTimelineValues).optional()),
+    /** Consent checkbox: value="true" when checked, otherwise missing. */
+    consent: z.preprocess((value) => (value === 'true' ? true : false), z.boolean()).optional(),
+    /** Optional hidden field supported by the action. */
+    'DataSubjectId': z.preprocess(emptyStringToUndefined, z.string().uuid().optional()),
+    /** Backwards-compatible optional fields (older contact forms). */
+    service: optionalTrimmedString(100),
+    website: optionalTrimmedString(200),
+    /** File uploads (not implemented in the UI yet). When implemented, we expect keys like file1..file5. */
+    file1: optionalFile(),
+    file2: optionalFile(),
+    file3: optionalFile(),
+    file4: optionalFile(),
+    file5: optionalFile(),
+  })
+  .passthrough()
 
 async function sendEmail(emailData: EmailData, files: FileAttachment[]): Promise<void> {
   if (!isProd()) {
@@ -34,7 +90,8 @@ async function sendEmail(emailData: EmailData, files: FileAttachment[]): Promise
 export const contact = {
   submit: defineAction({
     accept: 'form',
-    handler: async (form: FormData, context): Promise<{ success: true; message: string }> => {
+    input: contactFormInputSchema,
+    handler: async (input, context): Promise<{ success: true; message: string }> => {
       const route = '/_actions/contact/submit'
 
       try {
@@ -50,26 +107,8 @@ export const contact = {
           throw new ActionsFunctionError('Too many form submissions. Please try again later.', { status: 429 })
         }
 
-        const formData: ContactFormData = {
-          name: readString(form, 'name'),
-          email: readString(form, 'email'),
-          message: readString(form, 'message'),
-          consent: parseBoolean(form.get('consent')),
-        }
-
-        const phone = readString(form, 'phone')
-        const service = readString(form, 'service')
-        const budget = readString(form, 'budget')
-        const timeline = readString(form, 'timeline')
-        const website = readString(form, 'website')
-
-        if (phone) formData.phone = phone
-        if (service) formData.service = service
-        if (budget) formData.budget = budget
-        if (timeline) formData.timeline = timeline
-        if (website) formData.website = website
-
-        const files = await parseAttachments(form)
+        const formData = getFormDataFromInput(input)
+        const files = await parseAttachmentsFromInput(input)
 
         const validationErrors = validateInput(formData)
         if (validationErrors.length > 0) {