@scribe-platform/cli 0.2.2 → 0.5.0

package/skills/scribe-site-builder/recipes/forms.md

@@ -0,0 +1,231 @@
+# Recipe: forms
+
+A Site can have **as many forms as it likes**. Each one is a collection in
+`.scribe.yml` with `form: true`, each gets its own inbox and its own workflow in
+the admin, and each posts to the same endpoint with a different `collection`.
+
+Design the form however you want. Only the POST contract below is fixed.
+
+## 1. Declare the collection
+
+Write a spec file and apply it — don't hand-edit `.scribe.yml` in the repo, since
+the admin treats the committed file as the source of truth and will overwrite
+you:
+
+```yaml
+# rsvps.yml
+name: rsvps
+label: Event RSVPs
+description: Replies to the invitations on the events page.
+path: content/rsvps
+format: yaml
+form: true
+fields:
+  - { name: fullName,     type: string,  required: true }
+  - { name: email,        type: string,  required: true }
+  - { name: mobile,       type: string,  label: Mobile }
+  - { name: eventTitle,   type: string,  label: Event, required: true }
+  - { name: guests,       type: number }
+  - { name: attending,    type: boolean, label: I'll be there }
+  - { name: dietaryNotes, type: text }
+workflow:
+  states:
+    - { name: pending,   label: Awaiting reply, kind: needs-you }
+    - { name: waitlist,  label: Waitlisted,     kind: waiting }
+    - { name: confirmed, label: Confirmed,      kind: closed }
+    - { name: declined,  label: Declined,       kind: closed }
+```
+
+```
+scribe schema apply <site> --file rsvps.yml      # or --file - to pipe it in
+scribe schema show <site> rsvps                  # read it back
+```
+
+Rules the apply will enforce for you:
+
+- `status` and `createdAt` are **reserved** — they're columns on the submission,
+  not fields you declare.
+- A form collection may **not** declare an `image` field; a visitor-submitted
+  file has nowhere to be stored yet (RFC 0007).
+- `workflow.states` is a list of `{ name, label, kind }` where `kind` is
+  `needs-you`, `waiting` or `closed`. A new submission starts in the first
+  `needs-you` state, so order matters. `hidden: true` keeps a state out of the
+  filter dropdown.
+- `path` and `format` are ignored for a form collection (submissions live in the
+  database), but the parser still wants them.
+
+## 2. POST contract
+
+```
+POST /api/submissions?site=<slug>&collection=<name>
+```
+
+- **Body:** JSON, or `application/x-www-form-urlencoded`, or
+  `multipart/form-data`. Values are coerced to the declared types, so a checkbox
+  posting `"on"` becomes `true` and `"4"` becomes `4`. Posting real JSON types is
+  still better — it's unambiguous.
+- **Turnstile is required.** Send the widget's token as `cf-turnstile-response`.
+  A missing or empty token is a **401**, always — there is no bypass.
+- **Responses:** `200 {ok:true}`; `400` with a human-readable `error` for a
+  validation failure; `401` verification failed; `429` rate limited (per site and
+  IP, **shared across all of that Site's forms**); `503` with visitor-facing copy
+  in `error` when the database is unreachable — show that message as-is, it's
+  written for them; `502` when the Site's `.scribe.yml` is unusable.
+- **CORS** is allowed only from the Site's registered domain, so test from the
+  real host (or `localhost` against a local admin).
+
+Never report success on a non-2xx. A form that says "Thanks!" after a 503 loses
+the message.
+
+## 3. A form component
+
+Generic and schema-driven, which is the useful starting point when the fields
+come from `.scribe.yml`. Adapt or replace the markup freely.
+
+```astro
+---
+// src/components/ScribeForm.astro
+export interface Props {
+  site: string;
+  collection: string;
+  turnstileSiteKey: string;
+  fields: Array<{ name: string; label?: string; type: string; required?: boolean }>;
+  apiBase?: string;
+  submitLabel?: string;
+  /** Values the page knows that the visitor shouldn't retype, e.g. which event this is. */
+  prefill?: Record<string, string>;
+}
+
+const {
+  site, collection, turnstileSiteKey, fields,
+  apiBase = import.meta.env.PUBLIC_SCRIBE_API_URL || 'https://scribe.weaverdigital.io',
+  submitLabel = 'Send',
+  prefill = {},
+} = Astro.props;
+
+// Scoped to the collection so two forms can share a page.
+const formId = `scribe-form-${collection}`;
+
+function labelFor(f: { name: string; label?: string }) {
+  return f.label ?? f.name.replace(/([a-z0-9])([A-Z])/g, '$1 $2').replace(/[_-]+/g, ' ')
+    .replace(/^./, (c) => c.toUpperCase());
+}
+// Control comes from the declared type. Name-based guessing is only for the
+// keyboard hint on an email/phone input — never for required-ness or the control.
+function inputType(f: { name: string; type: string }) {
+  if (f.type === 'number') return 'number';
+  if (/mail/i.test(f.name)) return 'email';
+  if (/phone|mobile|tel|cell/i.test(f.name)) return 'tel';
+  return 'text';
+}
+---
+<form id={formId} data-site={site} data-collection={collection} data-endpoint={`${apiBase}/api/submissions`}>
+  {fields.map((f) => (
+    prefill[f.name] !== undefined ? (
+      <input type="hidden" name={f.name} value={prefill[f.name]} />
+    ) : f.type === 'boolean' ? (
+      <label class="checkbox">
+        <input name={f.name} type="checkbox" /> {labelFor(f)}
+      </label>
+    ) : f.type === 'text' ? (
+      <label>{labelFor(f)}<textarea name={f.name} required={f.required} rows="4"></textarea></label>
+    ) : (
+      <label>{labelFor(f)}<input name={f.name} type={inputType(f)} required={f.required} /></label>
+    )
+  ))}
+  <div class="cf-turnstile" data-sitekey={turnstileSiteKey}></div>
+  <button type="submit">{submitLabel}</button>
+  <p class="form-status" role="status" aria-live="polite"></p>
+</form>
+
+<script src="https://challenges.cloudflare.com/turnstile/v0/api.js" async defer></script>
+<script is:inline define:vars={{ formId }}>
+  (function () {
+    const form = document.getElementById(formId);
+    if (!form) return;
+    const statusEl = form.querySelector('.form-status');
+    const say = (m) => { if (statusEl) statusEl.textContent = m; };
+
+    form.addEventListener('submit', async (event) => {
+      event.preventDefault();
+
+      // Built per control rather than from FormData, so a checkbox sends a real
+      // boolean and an unchecked box sends `false` instead of being omitted.
+      const payload = {};
+      for (const el of form.elements) {
+        if (!el.name) continue;
+        if (el.type === 'checkbox') payload[el.name] = el.checked;
+        else if (el.type === 'number') payload[el.name] = el.value === '' ? null : Number(el.value);
+        else payload[el.name] = el.value;
+      }
+
+      const url = `${form.dataset.endpoint}?site=${encodeURIComponent(form.dataset.site)}`
+        + `&collection=${encodeURIComponent(form.dataset.collection)}`;
+
+      say('Sending…');
+      try {
+        const res = await fetch(url, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify(payload),
+        });
+        if (!res.ok) {
+          // The server's copy is written for the visitor on 400/503; prefer it.
+          const data = await res.json().catch(() => ({}));
+          say(data.error || "Sorry — we couldn't send that. Please try again.");
+          return;
+        }
+        form.reset();
+        say('Thanks — we got it.');
+      } catch {
+        say("Sorry — we couldn't reach us just now. Please call or email instead.");
+      }
+    });
+  })();
+</script>
+```
+
+Note `cf-turnstile-response`: the Turnstile widget injects a hidden input with
+that name into the form, so the loop above picks it up automatically. If you
+build the payload by hand, include it explicitly.
+
+## 4. Put it on a page
+
+Placement is entirely yours — the schema says nothing about where a form goes.
+Read the collection out of the schema and pass its fields in:
+
+```astro
+---
+// src/pages/events/[...slug].astro
+import ScribeForm from '../../components/ScribeForm.astro';
+import { loadScribeSchema } from '../../lib/scribe';   // see schema.md
+
+const schema = loadScribeSchema();
+const rsvps = schema.collections.find((c) => c.name === 'rsvps');
+const { event } = Astro.props;
+---
+<h2>Coming along?</h2>
+<ScribeForm
+  site={schema.site}
+  collection="rsvps"
+  turnstileSiteKey={schema.turnstileSiteKey}
+  fields={rsvps.fields}
+  submitLabel="Send my RSVP"
+  prefill={{ eventTitle: event.data.title }}
+/>
+```
+
+`prefill` is how a form on a detail page captures its context — the visitor
+never types which event they're replying to, and the submission arrives in the
+inbox already saying so.
+
+## Gotchas
+
+- **Two forms, one page:** fine, as long as element ids are unique. The snippet
+  above scopes everything to `scribe-form-<collection>`.
+- **`notify:` does not send email.** It's parsed and logged by a console mailer
+  only. Don't promise a client notifications (RFC 0009 is the real thing).
+- **Rate limiting is per Site and IP, not per form**, so hammering one form while
+  testing will also throttle the others.
+- **An unchecked checkbox in `FormData` is absent, not `false`.** The payload
+  loop above avoids this; if you use `FormData`, add a hidden companion input.

package/skills/scribe-site-builder/recipes/schema.md

@@ -0,0 +1,99 @@
+# Recipe: reading the schema
+
+`.scribe.yml` sits in the Site's repo root and is the contract between Scribe and
+the Site: it names the collections, their fields, where content lives, and which
+collections are forms. The admin keeps it current — editors change it through the
+UI and the CLI writes to it — so the committed copy is authoritative at build
+time.
+
+**Read it directly. Don't generate a config file from it.** Older sites have a
+`scripts/generate-config.mjs` that flattened the schema into a `site-config.ts`;
+that layer lost field types and could only ever represent one form, which is why
+RFC 0010 drops it.
+
+## A loader
+
+```ts
+// src/lib/scribe.ts
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { parse } from 'yaml';
+
+export interface ScribeField {
+  name: string;
+  type: 'string' | 'text' | 'number' | 'boolean' | 'date' | 'select' | 'rich-text' | 'image';
+  label?: string;
+  required?: boolean;
+  hidden?: boolean;
+  isBody?: boolean;
+  options?: Array<string | { value: string; label?: string }>;
+}
+
+export interface ScribeCollection {
+  name: string;
+  path: string;
+  format?: 'yaml' | 'yaml-frontmatter';
+  label?: string;
+  description?: string;
+  form?: boolean;
+  fields: ScribeField[];
+  view?: { primary?: string; sort?: string; fields?: string[] };
+  workflow?: { states?: Array<{ name: string; label?: string; kind?: string; hidden?: boolean }> };
+}
+
+export interface ScribeSchema {
+  site: string;
+  siteName?: string;
+  turnstileSiteKey?: string;
+  collections: ScribeCollection[];
+}
+
+let cached: ScribeSchema | undefined;
+
+/** Build-time only — reads the repo's own `.scribe.yml`. */
+export function loadScribeSchema(): ScribeSchema {
+  // Resolve from the working directory, NOT from `import.meta.url`. Astro
+  // bundles this module into `dist/.prerender/chunks/`, so a module-relative
+  // path looks for `.scribe.yml` next to the bundle and fails the build with
+  // `ENOENT: .../dist/.scribe.yml`.
+  cached ??= parse(readFileSync(resolve(process.cwd(), '.scribe.yml'), 'utf-8')) as ScribeSchema;
+  return cached;
+}
+
+export const formCollections = () => loadScribeSchema().collections.filter((c) => c.form === true);
+export const contentCollections = () => loadScribeSchema().collections.filter((c) => c.form !== true);
+export const collection = (name: string) =>
+  loadScribeSchema().collections.find((c) => c.name === name);
+```
+
+Needs `yaml` in the Site's dependencies (a `devDependency` is fine — this only
+runs at build time, and CI installs dev deps before `npm run build`).
+
+## What the keys mean
+
+| Key | Meaning |
+|---|---|
+| `site` | the Site slug — what you pass as `?site=` when submitting a form |
+| `siteName` | display name |
+| `turnstileSiteKey` | public Turnstile key for forms |
+| `collections[].path` | where content files live, relative to the repo root |
+| `collections[].format` | `yaml-frontmatter` (markdown with a body) or `yaml` (data only) |
+| `collections[].form` | `true` means submissions, not files — **no content to render** |
+| `fields[].isBody` | this field is the markdown body, not frontmatter |
+| `fields[].hidden` | internal; don't render it, don't put it on a form |
+| `view.primary` / `view.sort` | the editor's preferred title and sort field |
+
+A `form: true` collection has **no files in the repo** — its submissions are rows
+in Scribe's database, readable in the admin or via
+`scribe submission list`/`export`. Don't try to render it as content.
+
+## From the CLI instead
+
+Useful when you want the schema without a checkout, or to inspect it while
+working:
+
+```
+scribe schema show <site>              # readable summary
+scribe schema show <site> rsvps        # one collection
+scribe schema show <site> --json       # raw, for piping
+```