@jini-ai/agent-plugins 0.6.16 → 0.6.19

package/cloudflare/lib/dns.mjs

@@ -0,0 +1,32 @@
+import { createHash } from 'node:crypto';
+import { segment } from './api.mjs';
+
+/** A stable identifier stamped as a Cloudflare DNS record comment so a later publish can recognize
+ * (and safely patch) a CNAME record it created itself, versus one an operator manages by hand.
+ * Genericized from the OD origin's `od:cfp:` marker prefix. Keep existing Pages markers byte-identical. */
+export function dnsMarker({ resourceName, targetHost }, _options = {}) {
+  const short = ({ value }, _options = {}) => createHash('sha256').update(value).digest('hex').slice(0, 12);
+  return `jini-deploy:${short({ value: resourceName })}:${short({ value: targetHost })}`;
+}
+
+export function matchesHostname({ pattern, hostname }, _options = {}) {
+  const hostPattern = pattern.replace(/^https?:\/\//, '').split('/')[0].toLowerCase();
+  const expression = hostPattern.split('*').map(part => part.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('.*');
+  return new RegExp(`^${expression}$`).test(hostname);
+}
+
+/** Include mail/TXT/CAA in the review, but change only conflicting address records.
+ * Wildcard records are disclosed and preserved: exact hostname records override their DNS match. */
+export function planDns({ records, hostname, targetId, resourceName, zoneId, preserveWorkerDns }, _options = {}) {
+  const targetHost = `${resourceName}.pages.dev`;
+  const relevant = records.filter(record => matchesHostname({ pattern: record.name, hostname }) || (record.type === 'CAA' && hostname.endsWith(`.${record.name}`)));
+  // A Custom Domain already on this Worker owns its origin DNS. Never tear down that binding's
+  // managed address records merely because they are not Pages-style CNAMEs.
+  if (preserveWorkerDns) return { records: relevant, changes: [], dnsOwnership: 'worker-managed' };
+  const addresses = relevant.filter(record => record.name === hostname && ['A', 'AAAA', 'CNAME'].includes(record.type));
+  const exact = targetId === 'cloudflare-pages' && addresses.find(record => record.type === 'CNAME' && record.content.replace(/\.$/, '') === targetHost);
+  const path = `/zones/${segment({ value: zoneId })}/dns_records`;
+  const changes = addresses.filter(record => record !== exact).map(record => ({ method: 'DELETE', path: `${path}/${segment({ value: record.id })}`, hostname, before: record, reason: `Replace ${record.type} record ${record.id} for ${hostname}.` }));
+  if (targetId === 'cloudflare-pages' && !exact) changes.push({ method: 'POST', path, hostname, body: { type: 'CNAME', name: hostname, content: targetHost, proxied: true, ttl: 1, comment: dnsMarker({ resourceName, targetHost }) }, reason: `Point ${hostname} to ${targetHost}; Cloudflare flattens the apex CNAME.` });
+  return { records: relevant, changes, dnsOwnership: exact?.comment === dnsMarker({ resourceName, targetHost }) ? 'marked' : 'unmarked' };
+}

package/cloudflare/lib/domain-inventory.mjs

@@ -0,0 +1,61 @@
+import { segment, refusal, PAGES_PROJECTS_PAGING } from './api.mjs';
+import { matchesHostname } from './dns.mjs';
+
+/** Full account inventory, including disabled/no-script bindings. Never filter by destination first.
+ * @complexity At most 100 pages/list and 100 Pages projects; refuse beyond the cap, never truncate. */
+export async function readDomainInventory({ api, zone }, _options = {}) {
+  const records = await api.list({ path: `/zones/${segment({ value: zone.id })}/dns_records` });
+  const workers = await api.list({ path: `${api.accountPath}/workers/domains` });
+  const routes = await api.list({ path: `/zones/${segment({ value: zone.id })}/workers/routes` });
+  const projects = await api.list({ path: `${api.accountPath}/pages/projects` }, PAGES_PROJECTS_PAGING);
+  requireFields({ api, rows: records, fields: ['id', 'name', 'type', 'content'], label: 'DNS records' });
+  requireFields({ api, rows: workers, fields: ['id', 'hostname', 'service', 'environment'], label: 'Worker domains' });
+  requireFields({ api, rows: routes, fields: ['id', 'pattern'], label: 'Worker routes' });
+  requireFields({ api, rows: projects, fields: ['name'], label: 'Pages projects' });
+  if (projects.length > 100) throw refusal({ kit: api.kit, code: 'CLOUDFLARE_INVENTORY_UNKNOWN', message: 'More than 100 Pages projects need conflict inspection. Narrow the account or contact support before changing domains.' });
+  const pages = [];
+  for (const project of projects) {
+    const domains = await api.list({ path: `${api.accountPath}/pages/projects/${segment({ value: project.name })}/domains` }, PAGES_PROJECTS_PAGING);
+    requireFields({ api, rows: domains, fields: ['name', 'status'], label: `Pages project ${project.name} domains` });
+    pages.push(...domains.map(domain => ({ ...domain, projectName: project.name })));
+  }
+  return { records, workers, routes, pages };
+}
+
+function requireFields({ api, rows, fields, label }, _options = {}) {
+  const complete = rows.every(row => fields.every(field => typeof row?.[field] === 'string' && row[field].length > 0));
+  if (!complete) throw refusal({ kit: api.kit, code: 'CLOUDFLARE_INVENTORY_UNKNOWN', message: `${label} returned incomplete identities. Check read permissions and preview again before changing domains.`, status: 409 });
+  if (new Set(rows.map(row => row[fields[0]])).size !== rows.length) throw refusal({ kit: api.kit, code: 'CLOUDFLARE_INVENTORY_UNKNOWN', message: `${label} changed while paginating (repeated identities). Preview again before changing domains.`, status: 409 });
+}
+
+/** Current state and exact binding/route effects for one hostname; a route can affect BOTH names. */
+export function planBindings({ inventory, hostname, targetId, resourceName, zone, accountPath }, _options = {}) {
+  const workerBindings = inventory.workers.filter(binding => binding.hostname === hostname);
+  const pagesBindings = inventory.pages.filter(binding => binding.name === hostname);
+  const routes = inventory.routes.filter(route => matchesHostname({ pattern: route.pattern, hostname }));
+  const workers = workerBindings.filter(binding => targetId !== 'cloudflare-workers' || binding.service !== resourceName || binding.environment !== 'production' || binding.enabled === false);
+  const pages = pagesBindings.filter(binding => targetId !== 'cloudflare-pages' || binding.projectName !== resourceName);
+  const changes = [
+    ...workers.map(binding => ({ method: 'DELETE', path: `${accountPath}/workers/domains/${segment({ value: binding.id })}`, hostname, before: binding, reason: `Detach ${hostname} from Worker ${binding.service}.` })),
+    ...pages.map(binding => ({ method: 'DELETE', path: `${accountPath}/pages/projects/${segment({ value: binding.projectName })}/domains/${segment({ value: hostname })}`, hostname, before: binding, reason: `Detach ${hostname} from Pages project ${binding.projectName}.` })),
+    ...routes.map(route => ({ method: 'DELETE', path: `/zones/${segment({ value: zone.id })}/workers/routes/${segment({ value: route.id })}`, hostname, before: route, widerImpact: true, reason: `Remove entire overlapping route ${route.pattern} (${route.id}); this can affect other hostnames and paths. No automatic splitting.` })),
+  ];
+  const owned = targetId === 'cloudflare-workers'
+    ? workerBindings.some(binding => binding.service === resourceName && binding.environment === 'production' && binding.enabled !== false)
+    : pagesBindings.some(binding => binding.projectName === resourceName);
+  if (!owned) changes.push(attachment({ targetId, resourceName, zone, accountPath, hostname }));
+  if (owned && targetId === 'cloudflare-pages') changes.push(...pagesValidationRetry({ pagesBindings, resourceName, hostname, accountPath }));
+  return { workerBindings, pagesBindings, routes, changes, owned };
+}
+
+function pagesValidationRetry({ pagesBindings, resourceName, hostname, accountPath }, _options = {}) {
+  const current = pagesBindings.find(binding => binding.projectName === resourceName);
+  if (current.status === 'active') return [];
+  return [{ method: 'PATCH', path: `${accountPath}/pages/projects/${segment({ value: resourceName })}/domains/${segment({ value: hostname })}`, hostname, before: current,
+    reason: `Retry ${current.status} domain validation for ${hostname} on Pages project ${resourceName}.` }];
+}
+
+function attachment({ targetId, resourceName, zone, accountPath, hostname }, _options = {}) {
+  if (targetId === 'cloudflare-workers') return { method: 'PUT', path: `${accountPath}/workers/domains`, hostname, body: { hostname, service: resourceName, environment: 'production', zone_id: zone.id }, reason: `Attach ${hostname} to Worker ${resourceName}; Cloudflare manages DNS and certificates.` };
+  return { method: 'POST', path: `${accountPath}/pages/projects/${segment({ value: resourceName })}/domains`, hostname, body: { name: hostname }, reason: `Associate ${hostname} with Pages project ${resourceName} before creating its CNAME.` };
+}

package/cloudflare/lib/domain-status.mjs

@@ -0,0 +1,48 @@
+import { segment } from './api.mjs';
+
+/** Bounded polling with injected clock/sleep and policy-enforcing HTTPS content transport.
+ * At most 6 rounds; unfinished TLS/content is partial even if the hosting URL is ready. */
+export async function pollDomains({ api, kit, plan, proof }, { attempts = 6 } = {}) {
+  let states = [];
+  for (let attempt = 0; attempt < attempts; attempt += 1) {
+    states = [];
+    const workers = plan.targetId === 'cloudflare-workers' ? await workerState({ api, plan }) : null;
+    for (const { hostname } of plan.hostnames) states.push(await safeProbeHostname({ api, kit, plan, proof, hostname, workers }));
+    if (states.every(state => state.status === 'ready')) return states;
+    if (attempt + 1 < attempts) await kit.sleep(Math.min(1000 * 2 ** attempt, 8000));
+  }
+  return states;
+}
+
+async function safeProbeHostname(input, _options = {}) {
+  try { return await probeHostname(input); }
+  catch (error) { return { hostname: input.hostname, status: 'unknown', certificateStatus: 'unknown', contentVerified: false,
+    errorCode: error.code ?? 'CLOUDFLARE_DOMAIN_STATUS_UNKNOWN', message: `${input.hostname}: ${error.message} Check domain validation and read permissions in Cloudflare, then preview again.` }; }
+}
+
+async function workerState({ api, plan }, _options = {}) {
+  const bindings = await api.list({ path: `${api.accountPath}/workers/domains` });
+  const certificates = await api.request({ path: `/zones/${segment({ value: plan.zone.id })}/ssl/certificate_packs` });
+  // The certificate-packs list result is the array of packs; anything else proves no coverage.
+  return { bindings, certificates: Array.isArray(certificates) ? certificates : [] };
+}
+
+async function probeHostname({ api, kit, plan, proof, hostname, workers }, _options = {}) {
+  const state = workers ? workerHostnameState({ workers, plan, hostname }) : await pagesHostnameState({ api, plan, hostname });
+  const verified = state.active && typeof kit.probeContent === 'function' && await kit.probeContent({ url: `https://${hostname}${proof.path}`, expected: proof.expected });
+  return { hostname, url: `https://${hostname}`, status: verified ? 'ready' : 'pending', certificateStatus: state.certificateStatus, domainStatus: state.domainStatus ?? 'pending', contentVerified: Boolean(verified), message: verified ? `${hostname} serves the deployed content over HTTPS.` : `${hostname} is awaiting domain validation, certificate or deployed content. Recheck in Cloudflare, then preview and publish again to resume.` };
+}
+
+function workerHostnameState({ workers, plan, hostname }, _options = {}) {
+  const active = workers.bindings.some(binding => binding.hostname === hostname && binding.service === plan.resourceName && binding.environment === 'production' && binding.enabled !== false);
+  const certificate = workers.certificates.find(pack => pack.status === 'active' && pack.hosts?.some(host => certificateMatches({ host, hostname })));
+  return { active: active && Boolean(certificate), domainStatus: active ? 'active' : 'pending', certificateStatus: certificate ? 'active' : 'pending' };
+}
+function certificateMatches({ host, hostname }, _options = {}) {
+  if (host === hostname) return true;
+  return host.startsWith('*.') && hostname.split('.').length === host.split('.').length && hostname.endsWith(host.slice(1));
+}
+async function pagesHostnameState({ api, plan, hostname }, _options = {}) {
+  const domain = await api.request({ path: `${api.accountPath}/pages/projects/${segment({ value: plan.resourceName })}/domains/${segment({ value: hostname })}` });
+  return { active: domain.status === 'active', domainStatus: domain.status, certificateStatus: domain.status === 'active' ? 'active' : 'pending' };
+}

package/cloudflare/lib/domains.mjs

@@ -0,0 +1,95 @@
+import { createHash } from 'node:crypto';
+import { refusal } from './api.mjs';
+import { normalizeDomain, resolveZone } from './zones.mjs';
+import { planDns } from './dns.mjs';
+import { readDomainInventory, planBindings } from './domain-inventory.mjs';
+import { pollDomains } from './domain-status.mjs';
+
+/** Authenticated reads only. Unknown inventory always produces an empty executable change list.
+ * Both hostnames retain current records, bindings, routes and individual states for the later UI. */
+export async function previewDomains({ api, kit, targetId, resourceName, domain, zoneId }, _options = {}) {
+  const apex = normalizeDomain({ domain, kit });
+  const hostnames = [apex, `www.${apex}`];
+  try {
+    const zone = await resolveZone({ api, domain: apex, zoneId: zoneId ?? api.zoneId });
+    const inventory = await readDomainInventory({ api, zone });
+    const hosts = hostnames.map(hostname => planHostname({ inventory, hostname, targetId, resourceName, zone, accountPath: api.accountPath }));
+    // A wildcard route can occur in both host views. Remove it ONCE, with the full before-image.
+    const changes = [...new Map(hosts.flatMap(host => host.changes).map(change => [`${change.method}:${change.path}:${JSON.stringify(change.body)}`, change])).values()];
+    const details = { targetId, resourceName, accountId: api.accountId, zone, hostnames: hosts, changes };
+    return { ...details, inventoryStatus: 'complete', fingerprint: fingerprint({ details }), message: 'Review every change. DNS, binding and certificate propagation can interrupt the existing site. Mail, TXT and CAA records are preserved.' };
+  } catch (error) {
+    return { inventoryStatus: 'unknown', targetId, resourceName, hostnames: hostnames.map(hostname => ({ hostname, status: 'unknown' })), changes: [], errorCode: 'CLOUDFLARE_INVENTORY_UNKNOWN', message: `Cannot safely inspect ${apex}. ${error.message} Complete account/zone read permissions and preview again.` };
+  }
+}
+
+function planHostname(input, _options = {}) {
+  const bindings = planBindings(input);
+  const dns = planDns({ ...input, records: input.inventory.records, zoneId: input.zone.id, preserveWorkerDns: input.targetId === 'cloudflare-workers' && bindings.owned });
+  // Pages must be associated before DNS points at it. Conflicting records/bindings go first.
+  const all = [...bindings.changes, ...dns.changes];
+  const removals = all.filter(change => change.method === 'DELETE');
+  const additions = [...bindings.changes, ...dns.changes].filter(change => change.method !== 'DELETE');
+  return { hostname: input.hostname, status: all.length ? 'changes-required' : 'configured', certificateStatus: 'unknown', contentVerified: false,
+    records: dns.records, dnsOwnership: dns.dnsOwnership, workerBindings: bindings.workerBindings, pagesBindings: bindings.pagesBindings, routes: bindings.routes, changes: [...removals, ...additions] };
+}
+
+/** Sort keys and inventory arrays so API response ordering alone cannot invalidate consent. */
+function canonical({ value }, _options = {}) {
+  if (Array.isArray(value)) return value.map(item => canonical({ value: item })).sort((a, b) => JSON.stringify(a).localeCompare(JSON.stringify(b)));
+  if (value !== null && typeof value === 'object') return Object.fromEntries(Object.keys(value).sort().map(key => [key, canonical({ value: value[key] })]));
+  return value;
+}
+function fingerprint({ details }, _options = {}) {
+  return createHash('sha256').update(JSON.stringify(canonical({ value: details }))).digest('hex');
+}
+
+/** An approval is a server-held capability, never a serializable confirmed:true input.
+ * Reinspection happens BEFORE uploads/provisioning, so stale/unknown plans cause zero mutations. */
+export async function assertDomainApproval(input, _options = {}) {
+  const { api, kit, approval } = input;
+  if (typeof approval?.authorize !== 'function') throw refusal({ kit, code: 'CLOUDFLARE_DOMAIN_CONFIRMATION_REQUIRED', message: `Review the exact domain preview for ${input.domain} and confirm it through deployment_execute_static_publish in chat. A request flag cannot approve DNS or binding changes.`, status: 409 });
+  const plan = await previewDomains(input);
+  if (plan.inventoryStatus !== 'complete') throw refusal({ kit, code: 'CLOUDFLARE_INVENTORY_UNKNOWN', message: plan.message, status: 409 });
+  if (approval.plan.fingerprint !== plan.fingerprint) throw refusal({ kit, code: 'CLOUDFLARE_DOMAIN_PLAN_STALE', message: `${input.domain} changed since review. Preview and confirm the new records, bindings and routes.`, status: 409 });
+  if (!await approval.authorize({ fingerprint: plan.fingerprint, accountId: api.accountId })) throw refusal({ kit, code: 'CLOUDFLARE_DOMAIN_CONFIRMATION_REQUIRED', message: `Confirmation expired or does not match ${input.domain}. Preview and confirm again.`, status: 409 });
+  return { ...plan, authorize: approval.authorize };
+}
+
+/** Apply only the verified, human-approved change list. No rollback or step journal by owner scope.
+ * A failure remains partial and names all unfinished hostnames; rerun a fresh preview to resume. */
+export async function applyDomains({ api, kit, plan, proof }, _options = {}) {
+  try {
+    if (typeof plan.authorize !== 'function' || !await plan.authorize({ fingerprint: plan.fingerprint, accountId: api.accountId })) {
+      throw refusal({ kit, code: 'CLOUDFLARE_DOMAIN_CONFIRMATION_REQUIRED', message: `${plan.zone.name} needs a current human-confirmed preview. Preview and confirm again; no domain changes were applied.`, status: 409 });
+    }
+    // Uploads may take time. Verify the same approved write set again immediately before cutover.
+    const current = await previewDomains({ api, kit, targetId: plan.targetId, resourceName: plan.resourceName, domain: plan.zone.name, zoneId: plan.zone.id });
+    if (current.fingerprint !== plan.fingerprint) throw refusal({ kit, code: 'CLOUDFLARE_DOMAIN_PLAN_STALE', message: `${plan.zone.name} changed while hosting uploaded. Preview and confirm the new state; no domain changes were applied.`, status: 409 });
+    for (const change of plan.changes) await applyChange({ api, kit, change });
+    return await pollDomains({ api, kit, plan, proof });
+  } catch (error) {
+    return failedCutover({ api, kit, plan, proof, error });
+  }
+}
+
+async function applyChange({ api, kit, change }, _options = {}) {
+  if (change.method === 'DELETE' && change.path.includes('/dns_records/')) {
+    // Detaching a Worker Custom Domain can remove its DNS record for us. Re-read the collection
+    // instead of blindly deleting a now-missing record, or deleting an ID changed concurrently.
+    const path = change.path.slice(0, change.path.lastIndexOf('/'));
+    const records = await api.list({ path });
+    const current = records.find(record => record.id === change.before.id);
+    if (!current) return;
+    if (fingerprint({ details: current }) !== fingerprint({ details: change.before })) throw refusal({ kit, code: 'CLOUDFLARE_DOMAIN_PLAN_STALE', message: `${change.hostname} DNS record ${change.before.id} changed during cutover. Preview and confirm again.`, status: 409 });
+  }
+  await api.request({ path: change.path, method: change.method, ...(change.body ? { body: change.body } : {}) });
+}
+
+async function failedCutover({ api, kit, plan, proof, error }, _options = {}) {
+  let states;
+  try { states = await pollDomains({ api, kit, plan, proof }, { attempts: 1 }); }
+  catch { states = plan.hostnames.map(({ hostname }) => ({ hostname, certificateStatus: 'unknown', contentVerified: false })); }
+  return states.map(state => ({ ...state, status: state.status === 'ready' ? 'ready' : 'failed', operationFailed: true, errorCode: error.code ?? 'CLOUDFLARE_DOMAIN_FAILED',
+    message: `${state.hostname}: ${error.message} Hosting is retained. Preview again to inspect and resume the unfinished domain changes.` }));
+}

package/cloudflare/lib/forms.mjs

@@ -0,0 +1,254 @@
+import { readFile } from 'node:fs/promises';
+import { refusal, segment } from './api.mjs';
+
+/** Form submissions destination: one D1 database per site Worker plus the bundled receiver.
+ * Forms, fields and full validation stay in the host; this file only provisions storage and transport.
+ * The `TOVU_*` bindings, `tovu-forms-*` database names and `/_tovu/*` routes are frozen wire names:
+ * live Workers and D1 databases already use them. */
+export const FORMS_BINDING = 'TOVU_FORMS';
+export const FORMS_SECRET_BINDING = 'TOVU_FORMS_SECRET';
+/** Routed to the Worker before static assets, so a missing asset can never answer a form POST. */
+export const FORMS_WORKER_ROUTES = ['/forms/*', '/_tovu/*'];
+export const FREE_PLAN_NOTE = 'Free plan limits: 100,000 Worker requests/day, D1 100,000 row writes/day and 500 MB per database (shared with the rest of this Cloudflare account).';
+const D1_PAGING = { perPage: 100, maxPages: 10 };
+const SLUG = /^[a-z0-9][a-z0-9-]{0,99}$/;
+const FIELD_NAME = /^[A-Za-z0-9_.[\]-]{1,100}$/;
+const MAX_FORMS = 50;
+const MAX_FIELDS = 100;
+
+/** Forward-only, plugin-owned. Append a new version; never edit or reorder an applied one. */
+export const MIGRATIONS = Object.freeze([
+  { version: 1, sql: [
+    'CREATE TABLE IF NOT EXISTS submissions (seq INTEGER PRIMARY KEY AUTOINCREMENT, id TEXT NOT NULL UNIQUE, form_slug TEXT NOT NULL, answers_json TEXT NOT NULL, submitted_at TEXT NOT NULL, ip TEXT NULL, pulled_at TEXT NULL)',
+    'CREATE INDEX IF NOT EXISTS submissions_pending ON submissions (pulled_at, seq)',
+    'CREATE TABLE IF NOT EXISTS rate_windows (key TEXT PRIMARY KEY, window_start INTEGER NOT NULL, count INTEGER NOT NULL)',
+    'CREATE INDEX IF NOT EXISTS rate_windows_start ON rate_windows (window_start)',
+  ] },
+]);
+const MIGRATIONS_TABLE = 'CREATE TABLE IF NOT EXISTS schema_migrations (version INTEGER PRIMARY KEY, applied_at TEXT NOT NULL)';
+
+/** Validates the host's generic `formDestination` input. `null` means no active forms: assets-only Worker.
+ * @complexity O(forms * fields), both capped. */
+export function normalizeForms({ formDestination, kit }, { requireSecret = true } = {}) {
+  const forms = formDestination?.forms ?? [];
+  if (!Array.isArray(forms) || forms.length > MAX_FORMS) throw formsRefusal({ kit, message: `Expected at most ${MAX_FORMS} forms in the form manifest. Disable unused forms in the site admin, then publish again.` });
+  if (forms.length === 0) return null;
+  const secret = formDestination.secret;
+  if (requireSecret) checkReceiverSecret({ secret, kit });
+  return { forms: forms.map(form => normalizeForm({ form, kit })), secret };
+}
+
+function checkReceiverSecret({ secret, kit }, _options = {}) {
+  if (typeof secret !== 'string' || secret.length < 32) throw formsRefusal({ kit, message: 'The form receiver key is missing. Publish again from the site admin so it can create the key.' });
+}
+
+function normalizeForm({ form, kit }, _options = {}) {
+  if (!SLUG.test(form?.slug ?? '')) throw formsRefusal({ kit, message: `Form slug "${String(form?.slug).slice(0, 100)}" cannot be served here. Use lowercase letters, digits and hyphens, then publish again.` });
+  checkFieldCount({ form, kit });
+  const successPath = form.successPath;
+  checkSuccessPath({ form, successPath, kit });
+  return { slug: form.slug, fields: form.fields.map(field => normalizeField({ field, kit, slug: form.slug })), ...(successPath ? { successPath } : {}) };
+}
+
+function checkFieldCount({ form, kit }, _options = {}) {
+  if (!Array.isArray(form.fields) || form.fields.length === 0 || form.fields.length > MAX_FIELDS) throw formsRefusal({ kit, message: `Form ${form.slug} needs 1-${MAX_FIELDS} fields. Fix the form in the site admin, then publish again.` });
+}
+
+function checkSuccessPath({ form, successPath, kit }, _options = {}) {
+  if (successPath === undefined) return;
+  if (typeof successPath !== 'string' || !/^\/(?![/\\])[^\\\s]{0,499}$/.test(successPath)) throw formsRefusal({ kit, message: `Form ${form.slug} has an unusable success page. Use a path on this site starting with "/".` });
+}
+
+function normalizeField({ field, kit, slug }, _options = {}) {
+  if (!FIELD_NAME.test(field?.name ?? '')) throw formsRefusal({ kit, message: `Form ${slug} has a field name that cannot be served here. Rename the field in the site admin, then publish again.` });
+  const max = field.maxLength;
+  checkMaxLength({ max, kit, slug, name: field.name });
+  return { name: field.name, required: field.required === true, ...(Number.isInteger(max) ? { maxLength: max } : {}), ...(field.multiple === true ? { multiple: true } : {}) };
+}
+
+function checkMaxLength({ max, kit, slug, name }, _options = {}) {
+  if (max === undefined || max === null) return;
+  if (!(Number.isInteger(max) && max >= 1 && max <= 5000)) throw formsRefusal({ kit, message: `Form ${slug} field ${name} has an invalid maximum length. Use 1-5000.` });
+}
+
+function formsRefusal({ kit, message, status = 400, code = 'CLOUDFLARE_FORMS_INVALID' }, _options = {}) {
+  return refusal({ kit, code, message, status });
+}
+
+/** Stable per-site identity derived from the Worker name; never random, so republish reuses it. */
+export function databaseName({ resourceName }, _options = {}) {
+  return `tovu-forms-${resourceName}`.slice(0, 63);
+}
+
+const PERMISSION_STEP = 'Edit the saved Cloudflare API token: add Account > D1 > Edit (dashboard: My Profile > API Tokens > the token > Edit), keep its existing Workers permissions, then preview again.';
+
+/** Exact-name lookup. A 401/403 is reported as the missing D1 permission, never as "absent". */
+export async function findDatabase({ api, kit, name }, _options = {}) {
+  try {
+    const items = await api.list({ path: `${api.accountPath}/d1/database?name=${segment({ value: name })}` }, D1_PAGING);
+    return items.find(item => item.name === name) ?? null;
+  } catch (error) {
+    if (error.status === 401 || error.status === 403) throw formsRefusal({ kit, code: 'CLOUDFLARE_D1_PERMISSION_REQUIRED', status: 403, message: `Form submissions need D1 access. ${PERMISSION_STEP}` });
+    throw error;
+  }
+}
+
+/** Read-only preview lines for the publish confirmation. Pages has no receiver in v1.
+ * @complexity One bounded D1 inventory read. */
+export async function previewForms({ api, kit, resourceName, targetId, formDestination }, _options = {}) {
+  const normalized = normalizeForms({ formDestination, kit }, { requireSecret: false });
+  if (!normalized) return undefined;
+  const count = normalized.forms.length;
+  if (targetId !== 'cloudflare-workers') {
+    return { status: 'unsupported', forms: count, changes: [], message: `This site has ${count} active form(s), but Cloudflare Pages publishing cannot receive submissions yet. Publish to Cloudflare Workers to accept form submissions; on Pages the forms will not submit.` };
+  }
+  const name = databaseName({ resourceName });
+  let existing;
+  try { existing = await findDatabase({ api, kit, name }); }
+  catch (error) {
+    if (error.code !== 'CLOUDFLARE_D1_PERMISSION_REQUIRED') throw error;
+    return { status: 'permission-required', forms: count, changes: [], message: error.message.replace(/^CLOUDFLARE_D1_PERMISSION_REQUIRED: /, '') };
+  }
+  return { status: 'on', forms: count,
+    changes: [{ action: existing ? 'reuse' : 'create', resource: 'd1-database', name, ...(existing ? { databaseId: existing.uuid } : {}) },
+      { action: 'bind', resource: 'worker', resourceName, routes: FORMS_WORKER_ROUTES }],
+    message: `Form submissions: on (${count} form${count === 1 ? '' : 's'}). Submissions are stored in D1 database ${name} (${existing ? 'reused' : 'created'}) in this Cloudflare account and pulled into the site admin on demand. ${FREE_PLAN_NOTE}` };
+}
+
+/** Find-or-create the database, then apply pending migrations. Never drops or recreates anything.
+ * @complexity One inventory read, at most one create, 2 + pending-migration queries. */
+export async function provisionForms({ api, kit, resourceName }, _options = {}) {
+  const name = databaseName({ resourceName });
+  const database = await findDatabase({ api, kit, name }) ?? await createDatabase({ api, kit, name });
+  if (typeof database?.uuid !== 'string' || !database.uuid) throw formsRefusal({ kit, code: 'CLOUDFLARE_D1_INVALID', status: 502, message: `D1 database ${name} returned no id. Check it in the Cloudflare dashboard, then publish again.` });
+  const applied = await migrate({ api, kit, databaseId: database.uuid });
+  return { databaseId: database.uuid, databaseName: name, applied };
+}
+
+async function createDatabase({ api, kit, name }, _options = {}) {
+  try { return await api.request({ path: `${api.accountPath}/d1/database`, method: 'POST', body: { name } }); }
+  catch (error) {
+    // A concurrent publish may have created it first; the exact-name lookup is authoritative.
+    if (!error.details?.alreadyExists) throw error;
+    return findDatabase({ api, kit, name });
+  }
+}
+
+async function query({ api, databaseId, sql, params = [] }, _options = {}) {
+  const result = await api.request({ path: `${api.accountPath}/d1/database/${segment({ value: databaseId })}/query`, method: 'POST', body: { sql, params } });
+  return Array.isArray(result) ? result.flatMap(item => item?.results ?? []) : [];
+}
+
+/** Applies each missing version in order; returns the versions applied by this call. */
+export async function migrate({ api, kit, databaseId }, _options = {}) {
+  await query({ api, databaseId, sql: MIGRATIONS_TABLE });
+  const rows = await query({ api, databaseId, sql: 'SELECT version FROM schema_migrations' });
+  const done = new Set(rows.map(row => Number(row.version)));
+  const applied = [];
+  for (const migration of MIGRATIONS.filter(item => !done.has(item.version))) {
+    // Every statement is idempotent (IF NOT EXISTS), so a version interrupted before its marker reruns safely.
+    // One statement per request: the REST endpoint binds `params` to a single statement.
+    for (const sql of migration.sql) await query({ api, databaseId, sql });
+    await query({ api, databaseId, sql: 'INSERT OR IGNORE INTO schema_migrations (version, applied_at) VALUES (?, ?)', params: [migration.version, new Date(kit.now?.() ?? Date.now()).toISOString()] });
+    applied.push(migration.version);
+  }
+  return applied;
+}
+
+let receiverSource;
+/** The receiver module text, read once from this plugin's own folder (path-separator safe). */
+export async function receiverModule(_required = {}, _options = {}) {
+  receiverSource ??= await readFile(new URL('../worker/forms-receiver.mjs', import.meta.url), 'utf8');
+  return receiverSource;
+}
+
+const MAX_PAGE_ROUTES = 90;
+const FORM_MARKER = /<form\b[^>]*\bdata-form-slug="/i;
+/** Exact routes of exported pages that contain one of the site's forms, so the Worker runs first on
+ * them and can show the "sent" state after a submission. Other pages and every asset stay on the free
+ * static path. Over the cap only the first pages are listed; the submission itself works everywhere.
+ * @complexity O(HTML bytes). */
+export function formPageRoutes({ files }, { max = MAX_PAGE_ROUTES } = {}) {
+  const routes = [];
+  for (const file of files ?? []) {
+    const path = String(file.file ?? '').replaceAll('\\', '/').replace(/^\.?\//, '');
+    if (path.endsWith('.html') && FORM_MARKER.test(Buffer.from(file.data ?? '').toString('utf8'))) {
+      const page = routesForPage({ path });
+      if (routes.length + page.length > max) break;
+      routes.push(...page);
+    }
+  }
+  return routes;
+}
+
+/** `a/index.html` answers at `/a/` and `/a`; `a.html` at `/a.html` and `/a` (auto-trailing-slash). */
+function routesForPage({ path }, _options = {}) {
+  if (path === 'index.html') return ['/'];
+  if (path.endsWith('/index.html')) { const dir = `/${path.slice(0, -'index.html'.length)}`; return [dir, dir.slice(0, -1)]; }
+  return [`/${path}`, `/${path.slice(0, -'.html'.length)}`];
+}
+
+/** Worker modules and bindings for a site with forms. The manifest is compiled in; visitors never supply it. */
+export async function formsWorkerParts({ manifest, secret, databaseId }, { pageRoutes = [] } = {}) {
+  const main = "import { handleRequest } from './receiver.mjs';\nimport manifest from './forms-manifest.mjs';\nexport default { fetch: (request, env) => handleRequest({ request, env, manifest }) };\n";
+  return {
+    modules: [
+      { name: 'index.mjs', source: main },
+      { name: 'receiver.mjs', source: await receiverModule() },
+      { name: 'forms-manifest.mjs', source: `export default ${JSON.stringify({ forms: manifest.forms })};\n` },
+    ],
+    bindings: [{ type: 'd1', name: FORMS_BINDING, id: databaseId }, { type: 'secret_text', name: FORMS_SECRET_BINDING, text: secret }],
+    runWorkerFirst: [...FORMS_WORKER_ROUTES, ...pageRoutes],
+  };
+}
+
+/** Private pull API client. The receiver key travels only in the Authorization header. */
+async function receiverCall({ kit, destination, path, init = {} }, _options = {}) {
+  const origin = receiverOrigin({ kit, url: destination?.url });
+  if (typeof destination.secret !== 'string' || destination.secret.length < 32) throw formsRefusal({ kit, code: 'CLOUDFLARE_FORMS_KEY_REQUIRED', message: 'The form receiver key is missing. Republish the site so the host can reinstall it, then pull again.' });
+  const resp = await receiverFetch({ kit, origin, path, init, secret: destination.secret });
+  checkReceiverStatus({ kit, origin, resp });
+  try { return await resp.json(); }
+  catch { throw formsRefusal({ kit, code: 'CLOUDFLARE_FORMS_INVALID_RESPONSE', status: 502, message: `${origin} returned unreadable data. Republish the site, then pull again.` }); }
+}
+
+async function receiverFetch({ kit, origin, path, init, secret }, _options = {}) {
+  try { return await kit.fetch(`${origin}${path}`, { ...init, headers: { ...init.headers, Authorization: `Bearer ${secret}` }, redirect: 'error' }, { timeoutMs: kit.timeouts.QUICK }); }
+  catch { throw formsRefusal({ kit, code: 'CLOUDFLARE_FORMS_UNREACHABLE', status: 502, message: `${origin} could not be reached. Check the site is published, then pull again.` }); }
+}
+
+function checkReceiverStatus({ kit, origin, resp }, _options = {}) {
+  if (resp.status === 401) throw formsRefusal({ kit, code: 'CLOUDFLARE_FORMS_UNAUTHORIZED', status: 401, message: `${origin} refused the form receiver key. Republish the site to reinstall the key, then pull again.` });
+  if (resp.status === 404 || resp.status === 405) throw formsRefusal({ kit, code: 'CLOUDFLARE_FORMS_RECEIVER_MISSING', status: 404, message: `${origin} has no form receiver. Republish the site with at least one active form, then pull again.` });
+  if (!resp.ok) throw formsRefusal({ kit, code: 'CLOUDFLARE_FORMS_UNAVAILABLE', status: 502, message: `${origin} answered HTTP ${resp.status}. Retry the pull in a few minutes.` });
+}
+
+function receiverOrigin({ kit, url }, _options = {}) {
+  let parsed;
+  try { parsed = new URL(url); } catch { parsed = null; }
+  if (parsed?.protocol !== 'https:') throw formsRefusal({ kit, code: 'CLOUDFLARE_FORMS_ADDRESS', message: 'The published site address is missing or not https. Republish the site, then pull again.' });
+  return parsed.origin;
+}
+
+const hasRowIdentity = item => Number.isSafeInteger(item?.seq) && typeof item.id === 'string' && item.id.length > 0 && item.id.length <= 64;
+const hasRowBody = item => typeof item.formSlug === 'string' && item.answers !== null && typeof item.answers === 'object' && !Array.isArray(item.answers);
+const hasRowMeta = item => typeof item.submittedAt === 'string' && (item.ip === null || typeof item.ip === 'string');
+const isPending = item => hasRowIdentity(item) && hasRowBody(item) && hasRowMeta(item);
+
+function pendingPath({ after, limit }, _options = {}) {
+  return `/_tovu/forms/pending?after=${Number(after) || 0}&limit=${Math.min(100, Math.max(1, Number(limit) || 50))}`;
+}
+
+/** One page of unpulled submissions, oldest first. */
+export async function pullFormSubmissions({ kit, destination }, { after = 0, limit = 50 } = {}) {
+  const page = await receiverCall({ kit, destination, path: pendingPath({ after, limit }) });
+  const items = page?.items;
+  if (!Array.isArray(items) || items.length > 100 || !items.every(isPending)) throw formsRefusal({ kit, code: 'CLOUDFLARE_FORMS_INVALID_RESPONSE', status: 502, message: 'The form receiver returned an unexpected page. Republish the site, then pull again.' });
+  return { items, nextAfter: Number(page.nextAfter) || 0, hasMore: page.hasMore === true };
+}
+
+/** Marks rows the host has committed; only then are they no longer pending. */
+export async function acknowledgeFormSubmissions({ kit, destination, ids }, _options = {}) {
+  const result = await receiverCall({ kit, destination, path: '/_tovu/forms/ack', init: { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ ids }) } });
+  return { acknowledged: Number(result?.acknowledged) || 0 };
+}

package/cloudflare/lib/pages-upload.mjs

@@ -0,0 +1,51 @@
+import { refusal, segment } from './api.mjs';
+import { chunkUploads } from './assets.mjs';
+
+/** Pages' stable project address, shared by render preparation and upload results. O(name bytes). */
+export function pagesAddress({ resourceName }, _options = {}) { return `https://${resourceName}.pages.dev`; }
+
+/** Retains project names, upload tokens, hash dedup/upsert and config-file form fields.
+ * Root `_headers`/`_redirects` are their own deployment form fields, not assets (wrangler's
+ * `pages deploy` does the same and keeps them out of the manifest): uploaded as an asset, `_headers`
+ * would be served as a public file and its rules never applied. Only the root copy is config; a
+ * nested `_headers` stays an ordinary asset.
+ * @complexity O(unique assets + bytes) and bounded batches (100 files / 75 MiB encoded). */
+export async function uploadPages({ api, kit, resourceName, prepared }, _options = {}) {
+  const path = `${api.accountPath}/pages/projects/${segment({ value: resourceName })}`;
+  await ensureProject({ api, path, resourceName });
+  const token = await api.request({ path: `${path}/upload-token` });
+  if (!token.jwt) throw refusal({ kit, code: 'CLOUDFLARE_UPLOAD_TOKEN_REQUIRED', message: `Pages project ${resourceName} returned no upload token. Check Pages Edit permission and retry.`, status: 502 });
+  await uploadAssets({ api, kit, prepared, jwt: token.jwt });
+  const form = new FormData();
+  form.append('manifest', JSON.stringify(Object.fromEntries(Object.entries(prepared.manifest).map(([path, file]) => [path, file.hash]))));
+  form.append('branch', 'main');
+  for (const [name, data] of Object.entries(prepared.config)) form.append(name, new File([data], name));
+  const deployment = await api.request({ path: `${path}/deployments`, method: 'POST', body: form }, { timeoutMs: kit.timeouts.DEPLOY });
+  return { url: pagesAddress({ resourceName }), deploymentId: deployment.id };
+}
+
+async function ensureProject({ api, path, resourceName }, _options = {}) {
+  if (await api.request({ path }, { allowMissing: true })) return;
+  try { await api.request({ path: `${api.accountPath}/pages/projects`, method: 'POST', body: { name: resourceName, production_branch: 'main' } }, { timeoutMs: api.kit.timeouts.DEPLOY }); }
+  catch (error) {
+    // A concurrent publisher can create the same stable project between GET and POST.
+    if (error.status !== 409 && !error.details?.alreadyExists) throw error;
+    await api.request({ path });
+  }
+}
+
+async function uploadAssets({ api, kit, prepared, jwt }, _options = {}) {
+  const hashes = [...prepared.byHash.keys()];
+  const result = await api.request({ path: '/pages/assets/check-missing', method: 'POST', jwt, body: { hashes } });
+  const missing = Array.isArray(result) ? result : result.hashes;
+  if (!Array.isArray(missing)) throw refusal({ kit, code: 'CLOUDFLARE_ASSET_LOOKUP_INVALID', message: 'Pages returned an incomplete missing-assets list. Retry publishing.', status: 502 });
+  const files = missing.map(hash => {
+    const file = prepared.byHash.get(hash);
+    if (!file) throw refusal({ kit, code: 'CLOUDFLARE_ASSET_BUCKET_INVALID', message: `Pages requested unknown asset hash ${hash}. Retry publishing.`, status: 502 });
+    return file;
+  });
+  for (const batch of chunkUploads({ files })) {
+    await api.request({ path: '/pages/assets/upload', method: 'POST', jwt, body: batch.map(file => ({ key: file.hash, value: file.data.toString('base64'), metadata: { contentType: file.contentType }, base64: true })) }, { timeoutMs: kit.timeouts.UPLOAD });
+  }
+  await api.request({ path: '/pages/assets/upsert-hashes', method: 'POST', jwt, body: { hashes } });
+}