@open_mind/editor-sdk 0.2.0 → 0.2.1

package/README.md

@@ -5,10 +5,20 @@ Publicly downloadable React and Next.js integration SDK for the Fieldmatch visua
 ## Install
 
 ```bash
-npm install @open_mind/editor-sdk
+npm install @open_mind/editor-sdk@0.2.1
+npx fieldmatch-editor-sdk-init
+```
+
+No npm token or custom registry is required. The initializer also creates or supplements `.env.local` without overwriting existing values. Fill in:
+
+```ini
+NEXT_PUBLIC_FIELDMATCH_SITE_ID=your-site-id
+NEXT_PUBLIC_FIELDMATCH_EDITOR_ORIGIN=https://fieldmatch-canvas-editor.vercel.app
+CMS_INTERNAL_URL=https://fieldmatch-canvas-cms.vercel.app
+REVALIDATION_SECRET=a-shared-secret-configured-in-the-site-record
 ```
 
-No npm token or custom registry is required. Installation also:
+For a Next.js App Router project, it also creates `app/api/revalidate/route.ts` when that route is absent. Configure the matching revalidation URL and secret in the site's Fieldmatch record. It also:
 
 - installs the repository skill at `.agents/skills/fieldmatch-editable-components`;
 - creates `FIELDMATCH_EDITOR.md`, the integration registry and checklist; and
@@ -98,7 +108,7 @@ Field IDs are persistent content keys. Use stable names such as `page.section.el
 
 Image fields support the Fieldmatch media library. Video fields currently accept a direct HTTP(S) URL; this version does not upload video files.
 
-See the generated `FIELDMATCH_EDITOR.md` and use the `$fieldmatch-editable-components` skill for the full integration workflow, CSP, preview, and verification guidance.
+The `$fieldmatch-editable-components` skill is mandatory whenever adding or changing visitor-visible text, links, images, or videos. It ensures every such item is wrapped using the matching SDK component. See the generated `FIELDMATCH_EDITOR.md` for the full integration workflow, CSP, preview, and verification guidance.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open_mind/editor-sdk",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Public integration SDK for connecting React and Next.js sites to the Fieldmatch visual editor.",
   "type": "module",
   "sideEffects": false,

package/scripts/install-agent-assets.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-import { cp, mkdir, readFile, writeFile } from 'node:fs/promises'
+import { cp, mkdir, readFile, stat, writeFile } from 'node:fs/promises'
 import { dirname, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
@@ -9,12 +9,13 @@ const targetRoot = resolve(process.env.INIT_CWD || process.cwd())
 const force = process.argv.includes('--force')
 const startMarker = '<!-- fieldmatch-editor-sdk:start -->'
 const endMarker = '<!-- fieldmatch-editor-sdk:end -->'
+const environmentTemplate = `# Fieldmatch visual-editor configuration\n# Fill the blank values. Keep this file out of version control.\nNEXT_PUBLIC_FIELDMATCH_SITE_ID=\nNEXT_PUBLIC_FIELDMATCH_EDITOR_ORIGIN=https://fieldmatch-canvas-editor.vercel.app\nCMS_INTERNAL_URL=https://fieldmatch-canvas-cms.vercel.app\nREVALIDATION_SECRET=\n`
 const managedBlock = `${startMarker}
 ## Fieldmatch editable content
 
-When creating or changing content that should be editable through Fieldmatch, use the \`$fieldmatch-editable-components\` skill installed at \`.agents/skills/fieldmatch-editable-components\`.
+**Mandatory:** before creating or changing any visitor-visible text, link, image, or video, read and use the \`$fieldmatch-editable-components\` skill installed at \`.agents/skills/fieldmatch-editable-components\`. Wrap every such item with the matching Fieldmatch SDK component.
 
-Read and maintain \`FIELDMATCH_EDITOR.md\` as the integration registry. Only content explicitly intended for customer editing should use the SDK; keep layout, styling, behavior, authorization, prices, and application state in code unless requirements say otherwise.
+Read and maintain \`FIELDMATCH_EDITOR.md\` as the integration registry. Keep layout, styling, interaction behavior, authorization, calculations, and application state in code; do not use those as a reason to leave their visible text, links, images, or videos unwrapped.
 ${endMarker}`
 
 async function hasDirectDependency() {
@@ -27,6 +28,47 @@ async function hasDirectDependency() {
   }
 }
 
+async function ensureEnvironmentFile() {
+  const environmentTarget = resolve(targetRoot, '.env.local')
+  let existing = ''
+  try {
+    existing = await readFile(environmentTarget, 'utf8')
+  } catch {
+    // Start with the managed defaults when the project has no local environment file.
+  }
+
+  const missing = environmentTemplate
+    .split('\n')
+    .filter((line) => line && !line.startsWith('#'))
+    .filter((line) => !new RegExp(`^${line.split('=')[0]}=`, 'm').test(existing))
+
+  if (!existing) {
+    await writeFile(environmentTarget, environmentTemplate)
+  } else if (missing.length) {
+    await writeFile(environmentTarget, `${existing.trimEnd()}\n\n# Fieldmatch visual-editor configuration\n${missing.join('\n')}\n`)
+  }
+}
+
+async function ensureNextRevalidationRoute() {
+  for (const applicationRoot of ['app', 'src/app']) {
+    const routeTarget = resolve(targetRoot, applicationRoot, 'api/revalidate/route.ts')
+    try {
+      await readFile(routeTarget, 'utf8')
+      return 'existing'
+    } catch {
+      try {
+        if (!(await stat(resolve(targetRoot, applicationRoot))).isDirectory()) continue
+      } catch {
+        continue
+      }
+      await mkdir(dirname(routeTarget), { recursive: true })
+      await cp(resolve(packageRoot, 'templates/next-revalidate-route.ts'), routeTarget)
+      return 'created'
+    }
+  }
+  return 'not-next-app-router'
+}
+
 async function install() {
   if (process.env.FIELDMATCH_SKIP_AGENT_SETUP === '1') return
   if (targetRoot === packageRoot) return
@@ -39,6 +81,9 @@ async function install() {
     force: true,
   })
 
+  await ensureEnvironmentFile()
+  const revalidationRoute = await ensureNextRevalidationRoute()
+
   const guideTarget = resolve(targetRoot, 'FIELDMATCH_EDITOR.md')
   try {
     await readFile(guideTarget, 'utf8')
@@ -64,11 +109,11 @@ async function install() {
   }
   await writeFile(agentsTarget, agents)
 
-  process.stdout.write('[Fieldmatch] Installed agent skill and integration instructions. Restart your coding agent so it reloads AGENTS.md.\n')
+  const routeMessage = revalidationRoute === 'created' ? ' Added app/api/revalidate/route.ts.' : revalidationRoute === 'existing' ? ' Reused the existing revalidation route.' : ''
+  process.stdout.write(`[Fieldmatch] Installed the required agent skill, integration instructions, and missing .env.local entries.${routeMessage} Fill NEXT_PUBLIC_FIELDMATCH_SITE_ID and REVALIDATION_SECRET, then restart your coding agent.\n`)
 }
 
 install().catch((error) => {
   process.stderr.write(`[Fieldmatch] Agent setup skipped: ${error instanceof Error ? error.message : String(error)}\n`)
   process.exitCode = 0
 })
-

package/skills/fieldmatch-editable-components/SKILL.md

@@ -5,16 +5,16 @@ description: Integrate or update React and Next.js components that should be edi
 
 # Fieldmatch Editable Components
 
-Connect deliberately chosen website content to Fieldmatch while preserving the site's structure, design, accessibility, and local fallbacks.
+Connect every visitor-visible text, link, image, and video to Fieldmatch while preserving the site's structure, design, accessibility, and local fallbacks.
 
 ## Workflow
 
-1. Read `FIELDMATCH_EDITOR.md`. If it is absent, create it from the SDK's documented project guide structure before integrating fields.
+1. This skill is mandatory whenever a visitor-visible text, link, image, or video is created or changed. Read `FIELDMATCH_EDITOR.md` first. If it is absent, run `npx fieldmatch-editor-sdk-init` before integrating fields.
 2. Inspect the installed SDK version, existing server content fetch, preview handling, and nearest `EditorProvider`. Reuse one provider around the editable page area; never add a provider per field.
-3. Identify only content explicitly intended for customer editing. Keep layout, CSS, component behavior, authorization, prices, calculated values, and application state in code unless the requirement expressly includes them.
+3. Wrap every visitor-visible text, link, image, and video. Keep layout, CSS, component behavior, authorization, prices, calculated values, and application state in code, but still wrap the visible labels, copy, links, images, and videos that those features render.
 4. Assign each field a stable, unique ID in `page.section.element` form. Do not silently rename or reuse IDs. An ID rename is a content migration.
 5. Choose the matching SDK component and preserve the original DOM semantics, classes, accessibility attributes, behavior, and meaningful local fallback.
-6. Update the field registry in `FIELDMATCH_EDITOR.md` with the ID, page, type, source component, fallback, and limitations.
+6. Update the field registry in `FIELDMATCH_EDITOR.md` with every ID, page, type, source component, fallback, and limitation.
 7. Verify normal rendering, editor selection, draft persistence, publish behavior, revalidation, and secret handling.
 
 ## Map content to components

package/skills/fieldmatch-editable-components/references/component-patterns.md

@@ -1,5 +1,11 @@
 # Fieldmatch component patterns
 
+## Required coverage
+
+Wrap every visitor-visible text, link, image, and video with the corresponding SDK component. Keep only layout, styling, interactivity, authorization, calculations, and state in application code. If one of those features renders visible copy or media, wrap that visible value too.
+
+Run `npx fieldmatch-editor-sdk-init` before integration. It creates or supplements `.env.local` with `NEXT_PUBLIC_FIELDMATCH_SITE_ID`, `NEXT_PUBLIC_FIELDMATCH_EDITOR_ORIGIN`, `CMS_INTERNAL_URL`, and `REVALIDATION_SECRET`; supply the deployment-specific values before running the site.
+
 ## Server content and local fallbacks
 
 Fetch content on the server and merge it with local defaults. Public requests use `published`; only authenticated preview flows may request `draft` with a server-only token.
@@ -109,4 +115,3 @@ Publishing should call a protected site endpoint that verifies the shared revali
 4. Confirm the public site has not changed before publishing.
 5. Publish, then confirm revalidation makes the new content public.
 6. Inspect the client bundle and network requests for leaked tokens or secrets.
-

package/templates/FIELDMATCH_EDITOR.md

@@ -1,6 +1,6 @@
 # Fieldmatch editor integration
 
-This file is the project-specific source of truth for content connected to `@open_mind/editor-sdk`. Keep it current whenever editable content is added, renamed, moved, or removed. Do not place tokens or secrets here.
+This file is the project-specific source of truth for content connected to `@open_mind/editor-sdk`. Keep it current whenever visitor-visible text, links, images, or videos are added, renamed, moved, or removed. Do not place tokens or secrets here.
 
 ## Project configuration
 
@@ -21,10 +21,11 @@ This file is the project-specific source of truth for content connected to `@ope
 
 - Render one `EditorProvider` around the editable area; do not create a provider per field.
 - Fetch published content for normal visitors. Fetch draft content only in authenticated preview/editor mode.
+- **Mandatory:** use the `$fieldmatch-editable-components` skill whenever adding or changing visitor-visible text, links, images, or videos. Wrap every such item with the matching SDK component.
 - Every editable field must have a stable, unique ID such as `home.hero.title` and a meaningful local fallback.
 - Do not silently rename or reuse an existing field ID. Treat an ID change as a content migration.
 - Use `EditableText` for text, textarea, rich-text strings, and button labels; `EditableLink` for destinations; `EditableImage` for images; and `EditableVideo` for direct video URLs.
-- Keep structure, styling, accessibility, behavior, permissions, prices, and application state in code unless the product requirement explicitly makes them editable content.
+- Keep structure, styling, accessibility, behavior, permissions, prices, and application state in code. Their visible text, links, images, and videos remain editable fields.
 - When wrapping custom components, make sure the final DOM element receives the props and event handlers supplied by the SDK.
 - Image selection supports the Fieldmatch media library. Video currently accepts a direct HTTP(S) URL; video upload and poster editing are not provided by this SDK version.
 - Keep the site CSP `frame-ancestors` restricted to the exact Fieldmatch editor origin. Never use a wildcard.
@@ -37,4 +38,3 @@ This file is the project-specific source of truth for content connected to `@ope
 - [ ] Draft edits survive a refresh and remain invisible on the public site before publishing.
 - [ ] Publish updates the public site and triggers revalidation successfully.
 - [ ] No CMS token, preview token, or revalidation secret is shipped to the browser.
-

package/templates/next-revalidate-route.ts

@@ -0,0 +1,21 @@
+import { createHmac, timingSafeEqual } from 'node:crypto'
+import { revalidatePath } from 'next/cache'
+import { NextResponse } from 'next/server'
+
+export async function POST(request: Request) {
+  const body = await request.text()
+  const secret = process.env.REVALIDATION_SECRET?.trim()
+
+  if (!secret && process.env.NODE_ENV === 'production') {
+    return NextResponse.json({ error: 'Revalidation is not configured.' }, { status: 503 })
+  }
+
+  const expected = createHmac('sha256', secret || 'development-revalidation-secret').update(body).digest()
+  const received = Buffer.from(request.headers.get('x-agency-signature') ?? '', 'hex')
+  if (received.length !== expected.length || !timingSafeEqual(received, expected)) {
+    return NextResponse.json({ error: 'Invalid webhook signature.' }, { status: 403 })
+  }
+
+  revalidatePath('/')
+  return NextResponse.json({ revalidated: true })
+}