Add Router Forms MVP

.env.example

@@ -1,5 +1,10 @@
 RESEND_API_KEY=your_resend_api_key_here
+ROUTER_EMAIL_FROM=info@router.so
+ROUTER_APP_URL=http://localhost:3000
 AUTH_SECRET=your_nextauth_secret_here
+FORM_SUBMISSION_SECRET=replace_with_a_long_random_secret
+FORMS_NAV_ENABLED=false
+FORMS_PUBLIC_ENABLED=true
 NODE_ENV=development
 
 # optional if you want to do GitHub OAuth
@@ -13,3 +18,11 @@ POSTGRES_URL="postgres://user:password@host:port/database?sslmode=require"
 # You can get your PostHog key from https://app.posthog.com/organization/settings
 NEXT_PUBLIC_POSTHOG_KEY=your_posthog_key_here
 NEXT_PUBLIC_POSTHOG_HOST=app.posthog.com
+
+# Stripe is optional for credential-free builds. Configure these only when enabling billing.
+STRIPE_SECRET_KEY=sk_test_...
+STRIPE_WEBHOOK_SECRET=whsec_...
+STRIPE_PRO_MONTHLY_PRICE_ID=price_...
+STRIPE_PRO_ANNUAL_PRICE_ID=price_...
+STRIPE_BUSINESS_MONTHLY_PRICE_ID=price_...
+STRIPE_BUSINESS_ANNUAL_PRICE_ID=price_...

.github/workflows/ci.yml

@@ -0,0 +1,118 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  application:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 9.15.9
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm lint
+      - run: pnpm typecheck
+      - run: pnpm test:unit
+      - name: Credential-free production build
+        run: pnpm build
+        env:
+          AUTH_SECRET: credential-free-build-secret-for-ci-only
+          FORM_SUBMISSION_SECRET: credential-free-form-secret-for-ci-only
+          FORM_RATE_LIMIT_SECRET: credential-free-rate-secret-for-ci-only
+
+  postgres:
+    runs-on: ubuntu-latest
+    services:
+      postgres:
+        image: postgres:16
+        env:
+          POSTGRES_USER: postgres
+          POSTGRES_PASSWORD: postgres
+          POSTGRES_DB: router_test
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U postgres"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 9.15.9
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - name: Apply forward migrations
+        env:
+          PGURL: postgresql://postgres:postgres@localhost:5432/router_test
+        run: |
+          chmod +x scripts/test-forward-migrations.sh
+          scripts/test-forward-migrations.sh
+      - run: pnpm test:db
+        env:
+          TEST_DATABASE_URL: postgresql://postgres:postgres@localhost:5432/router_test
+
+  browser:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 9.15.9
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm exec playwright install --with-deps chromium
+      - run: pnpm test:browser
+
+  wordpress:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - uses: shivammathur/setup-php@v2
+        with:
+          php-version: "7.4"
+      - run: chmod +x integrations/wordpress/check.sh integrations/wordpress/package.sh
+      - run: integrations/wordpress/check.sh
+
+  wordpress-runtime:
+    runs-on: ubuntu-latest
+    timeout-minutes: 25
+    strategy:
+      fail-fast: false
+      matrix:
+        config: [".wp-env.6.6.json", ".wp-env.latest.json"]
+        theme: ["twentytwentyfour", "twentytwentyone"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 9.15.9
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm exec playwright install --with-deps chromium
+      - run: pnpm exec wp-env start --config="${{ matrix.config }}" --update
+      - run: chmod +x integrations/wordpress/test-matrix.sh
+      - run: integrations/wordpress/test-matrix.sh "${{ matrix.config }}" "${{ matrix.theme }}"
+      - if: always()
+        run: pnpm exec wp-env stop --config="${{ matrix.config }}"

.gitignore

@@ -8,6 +8,8 @@
 
 # testing
 /coverage
+/playwright-report/
+/test-results/
 
 # next.js
 /.next/
@@ -34,7 +36,9 @@ yarn-error.log*
 
 # typescript
 *.tsbuildinfo
-next-env.d.ts
 
 .vscode
-.zshrc
+.zshrc
+
+# generated WordPress release artifacts (the public release ZIP is tracked)
+/integrations/wordpress/dist/

.wp-env.6.6.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://schemas.wp.org/trunk/wp-env.json",
+  "core": "WordPress/WordPress#6.6",
+  "phpVersion": "7.4",
+  "plugins": [
+    "./integrations/wordpress/router-forms",
+    "./integrations/wordpress/test-fixtures/router-forms-test-api"
+  ],
+  "testsEnvironment": false,
+  "port": 8888
+}

.wp-env.latest.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://schemas.wp.org/trunk/wp-env.json",
+  "core": null,
+  "phpVersion": "7.4",
+  "plugins": [
+    "./integrations/wordpress/router-forms",
+    "./integrations/wordpress/test-fixtures/router-forms-test-api"
+  ],
+  "testsEnvironment": false,
+  "port": 8888
+}

README.md

@@ -6,6 +6,8 @@
 
 This is a simple router for forms. [Watch a Demo](https://x.com/youngbloodcyb/status/1831808232966516972)
 
+Router supports optional first-class forms without changing its headless endpoint contract. Forms can be published on `forms.router.so`, embedded in an approved website, or rendered through the included WordPress block and shortcode. See [the Forms implementation notes](docs/forms/README.md) and [release runbook](docs/forms/release-runbook.md).
+
 # Self-Hosting router
 
 ## Prerequisites

__tests__/cron-config.test.ts

@@ -0,0 +1,15 @@
+import { readFileSync } from "node:fs";
+import { describe, expect, it } from "vitest";
+
+describe("scheduled maintenance", () => {
+  it("runs form rate-bucket pruning at least hourly", () => {
+    const config = JSON.parse(readFileSync("vercel.json", "utf8")) as {
+      crons: Array<{ path: string; schedule: string }>;
+    };
+
+    expect(config.crons).toContainEqual({
+      path: "/api/cron/forms-maintenance",
+      schedule: "17 * * * *",
+    });
+  });
+});

__tests__/embed-runtime.test.ts

@@ -0,0 +1,180 @@
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import type { FormDefinitionV1 } from "../lib/forms/definition";
+import { FORM_STARTERS } from "../lib/forms/starters";
+
+const runtimeSource = readFileSync(resolve("public/embed/v1.js"), "utf8");
+
+const definition: FormDefinitionV1 = {
+  version: 1,
+  title: "All fields",
+  description: "Runtime coverage",
+  submitLabel: "Send",
+  completion: { type: "message", message: "Thanks" },
+  fields: [
+    { id: "text", key: "text", kind: "text", label: "Text", required: true },
+    { id: "email", key: "email", kind: "email", label: "Email", required: true },
+    { id: "phone", key: "phone", kind: "phone", label: "Phone", required: false },
+    { id: "url", key: "url", kind: "url", label: "URL", required: false },
+    { id: "date", key: "date", kind: "date", label: "Date", required: false },
+    { id: "number", key: "number", kind: "number", label: "Number", required: false },
+    { id: "textarea", key: "textarea", kind: "textarea", label: "Long text", required: false },
+    { id: "select", key: "select", kind: "select", label: "Select", required: false, options: [{ id: "select_a", label: "A", value: "a" }] },
+    { id: "radio", key: "radio", kind: "radio", label: "Radio", required: false, options: [{ id: "radio_a", label: "A", value: "a" }] },
+    { id: "checkbox", key: "checkbox", kind: "checkbox", label: "Checkbox", required: false },
+    { id: "group", key: "group", kind: "checkbox-group", label: "Group", required: false, options: [{ id: "group_a", label: "A", value: "a" }] },
+    { id: "yesno", key: "yesno", kind: "yes-no", label: "Yes or no", required: false },
+    { id: "switch", key: "switch", kind: "switch", label: "Switch", required: false },
+    { id: "slider", key: "slider", kind: "slider", label: "Slider", required: false, validation: { min: 1, max: 10, step: 1 } },
+  ],
+};
+
+describe("embed v1 runtime", () => {
+  beforeEach(() => {
+    document.head.innerHTML = "";
+    document.body.innerHTML = "";
+    delete (window as unknown as { RouterFormsV1?: unknown }).RouterFormsV1;
+    window.eval(runtimeSource);
+  });
+
+  afterEach(() => {
+    document.body.innerHTML = "";
+  });
+
+  it("renders all field kinds with native labels and no framework wrapper", async () => {
+    const target = document.createElement("div");
+    document.body.appendChild(target);
+    const runtime = (window as unknown as {
+      RouterFormsV1: { mount: (target: Element, options: object) => Promise<void> };
+    }).RouterFormsV1;
+
+    await runtime.mount(target, { definition, publicId: "preview", preview: true });
+
+    expect(target.querySelector("h2")?.textContent).toBe("All fields");
+    expect(target.querySelectorAll("[data-router-field]")).toHaveLength(14);
+    expect(target.querySelector('input[type="email"]')).not.toBeNull();
+    expect(target.querySelector('input[type="range"]')).not.toBeNull();
+    expect(target.querySelectorAll("[required]").length).toBeGreaterThan(0);
+    expect(target.querySelectorAll("fieldset > legend")).toHaveLength(3);
+    expect(target.querySelector("[data-reactroot]")).toBeNull();
+  });
+
+  it("mounts multiple previews independently and installs scoped styles once", async () => {
+    const first = document.createElement("div");
+    const second = document.createElement("div");
+    document.body.append(first, second);
+    const runtime = (window as unknown as {
+      RouterFormsV1: { mount: (target: Element, options: object) => Promise<void> };
+    }).RouterFormsV1;
+
+    await Promise.all([
+      runtime.mount(first, { definition, publicId: "one", preview: true }),
+      runtime.mount(second, { definition, publicId: "two", preview: true }),
+    ]);
+
+    expect(first.querySelector("form")).not.toBeNull();
+    expect(second.querySelector("form")).not.toBeNull();
+    expect(document.querySelectorAll("#router-forms-v1-styles")).toHaveLength(1);
+  });
+
+  it("installs runtime styles in an iframe preview document", async () => {
+    const iframe = document.createElement("iframe");
+    document.body.appendChild(iframe);
+    const iframeDocument = iframe.contentDocument!;
+    const target = iframeDocument.createElement("div");
+    iframeDocument.body.appendChild(target);
+    const runtime = (window as unknown as {
+      RouterFormsV1: { mount: (target: Element, options: object) => Promise<void> };
+    }).RouterFormsV1;
+
+    await runtime.mount(target, {
+      definition,
+      publicId: "iframe-preview",
+      preview: true,
+    });
+
+    expect(target.querySelector("form")).not.toBeNull();
+    expect(iframeDocument.querySelectorAll("#router-forms-v1-styles")).toHaveLength(
+      1
+    );
+  });
+
+  it("allows any option to satisfy a required checkbox group", async () => {
+    const target = document.createElement("div");
+    document.body.appendChild(target);
+    const runtime = (window as unknown as {
+      RouterFormsV1: { mount: (target: Element, options: object) => Promise<void> };
+    }).RouterFormsV1;
+    const groupDefinition: FormDefinitionV1 = {
+      ...definition,
+      fields: [
+        {
+          id: "group",
+          key: "group",
+          kind: "checkbox-group",
+          label: "Group",
+          required: true,
+          options: [
+            { id: "group_a", label: "A", value: "a" },
+            { id: "group_b", label: "B", value: "b" },
+          ],
+        },
+      ],
+    };
+
+    await runtime.mount(target, {
+      definition: groupDefinition,
+      publicId: "required-group",
+      preview: true,
+    });
+
+    const form = target.querySelector("form")!;
+    const checkboxes = target.querySelectorAll<HTMLInputElement>('input[type="checkbox"]');
+    checkboxes[1].click();
+    expect(form.checkValidity()).toBe(true);
+  });
+
+  it("uses unique control IDs when the same form is mounted twice", async () => {
+    const first = document.createElement("div");
+    const second = document.createElement("div");
+    document.body.append(first, second);
+    const runtime = (window as unknown as {
+      RouterFormsV1: { mount: (target: Element, options: object) => Promise<void> };
+    }).RouterFormsV1;
+
+    await Promise.all([
+      runtime.mount(first, { definition, publicId: "duplicate", preview: true }),
+      runtime.mount(second, { definition, publicId: "duplicate", preview: true }),
+    ]);
+
+    const ids = Array.from(document.querySelectorAll<HTMLElement>("[id]"))
+      .map((element) => element.id)
+      .filter((id) => id !== "router-forms-v1-styles");
+    expect(new Set(ids).size).toBe(ids.length);
+  });
+
+  it.each(Object.entries(FORM_STARTERS))(
+    "renders the %s starter through the production runtime",
+    async (_starterId, starter) => {
+      const target = document.createElement("div");
+      document.body.appendChild(target);
+      const runtime = (window as unknown as {
+        RouterFormsV1: {
+          mount: (target: Element, options: object) => Promise<void>;
+        };
+      }).RouterFormsV1;
+
+      await runtime.mount(target, {
+        definition: starter,
+        publicId: `starter-${_starterId}`,
+        preview: true,
+      });
+
+      expect(target.querySelector("form")).not.toBeNull();
+      expect(target.querySelectorAll("[data-router-field]")).toHaveLength(
+        starter.fields.length
+      );
+    }
+  );
+});