@aeptus/aexeo-emdash 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -6,6 +6,58 @@ and the project follows [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.1.2] - 2026-04-28
+
+Functional patch. Three bugs flagged by the aeptus web team after
+testing 0.1.1 against emdash 0.8.0; same `wasm/` as `0.1.0` (no
+rule-engine change).
+
+**Compatibility:** verified against emdash `0.7.0` and `0.8.0`.
+
+### Fixed
+
+- **Duplicate "SEO findings" sidebar entry.** The descriptor and
+  the runtime admin both declared `/` AND `/findings` as adminPages
+  with the same label, so emdash rendered two duplicate links.
+  Drop the `/` entry — root-URL navigation
+  (`/admin/plugins/<id>/`) still works because the dispatcher in
+  `src/configured.ts` aliases the empty page name to the findings
+  page.
+
+### Added
+
+- **`seogeoPlugin({ collections })` option** for configured mode.
+  Lets sites with non-default collection slugs override which
+  collections the Refresh button sweeps. Defaults to
+  `["posts", "pages"]` when omitted (the slugs from
+  `@emdash-cms/template-blog-cloudflare`). Pointing at a missing
+  slug is non-fatal — the bridge returns empty and the sweep
+  records the missing collection in the Refresh summary's `errors`.
+- The Refresh sweep now threads the resolved collection list
+  through `handleAdminRoute` → `handleRefresh` →
+  `evaluateAndPersistAll` so the runtime honors what the descriptor
+  passed.
+
+## [0.1.1] - 2026-04-28
+
+Documentation-only patch. No runtime changes — same `dist/` and
+`wasm/` as `0.1.0`. Bumping the patch so npm consumers can resolve
+to the documented version of INSTALL.md / CHANGELOG.md without
+having to read this repo directly.
+
+### Changed
+
+- INSTALL.md now has a structured "Updating" section covering
+  routine plugin updates, emdash updates, joint updates, and the
+  verification steps for each. Establishes the rule "update one
+  thing at a time, never both in the same deploy" so failure
+  bisects stay clean.
+- CHANGELOG.md compatibility section calls out the verified emdash
+  range explicitly (`0.7.0` and `0.8.0`), names the upstream PR
+  (#734) that fixes the sandboxed-mode `content:afterSave` bridge
+  bug on `0.8.0`, and sets the convention for future releases to
+  record their tested range the same way.
+
 ## [0.1.0] - 2026-04-28
 
 First public release.
@@ -34,12 +86,21 @@ First public release.
 
 ### Compatibility
 
-- emdash `>= 0.7.0`
-- `@astrojs/cloudflare` adapter (Cloudflare Workers target). The
-  plugin will silently noop on the Node adapter.
-- `vite-plugin-wasm` required in the consumer's `astro.config.mjs`
-  vite plugins for the WASM import to resolve as a precompiled
-  `WebAssembly.Module`.
+- **emdash:** verified against `0.7.0` and `0.8.0`. Both modes work
+  on `0.7.0`; configured mode is recommended. On `0.8.0` the
+  sandboxed mode's `content:afterSave` hook also works (upstream
+  PR #734 wraps deferred plugin hooks in `after()` so bridge
+  bindings stay valid past the response — fixes the
+  silent-eval-skip behavior we worked around with the manual
+  Refresh button on `0.7.x`).
+- **Adapter:** `@astrojs/cloudflare`. The plugin uses
+  Cloudflare-specific APIs and will silently no-op on the Node
+  adapter.
+- **Vite plugin:** `vite-plugin-wasm` is required in the consumer's
+  `astro.config.mjs` for the WASM import to resolve to a
+  precompiled `WebAssembly.Module`. Not optional.
 
-[Unreleased]: https://github.com/schiste/Aexeo/compare/seogeo-plugin-v0.1.0...HEAD
-[0.1.0]: https://github.com/schiste/Aexeo/releases/tag/seogeo-plugin-v0.1.0
+[Unreleased]: https://github.com/schiste/Aexeo/compare/aexeo-emdash-v0.1.2...HEAD
+[0.1.2]: https://github.com/schiste/Aexeo/compare/aexeo-emdash-v0.1.1...aexeo-emdash-v0.1.2
+[0.1.1]: https://github.com/schiste/Aexeo/compare/aexeo-emdash-v0.1.0...aexeo-emdash-v0.1.1
+[0.1.0]: https://github.com/schiste/Aexeo/releases/tag/aexeo-emdash-v0.1.0

package/INSTALL.md

@@ -117,15 +117,102 @@ compiles into the deployed Worker artifact.
 
 ## Updating
 
+There are two things that can be updated independently — the plugin
+package and emdash itself. **Update one at a time, never both in the
+same deploy.** That way if something breaks, you know which side
+introduced the regression.
+
+### Updating the plugin
+
+For a routine patch / minor update within your existing semver range:
+
 ```bash
 npm update @aeptus/aexeo-emdash
-npm run build && <your deploy command>
+npm run build
+# Your usual deploy command
 ```
 
+For a major version bump (e.g. from `^0.x` to `^1.x`):
+
+1. Read the [CHANGELOG](./CHANGELOG.md) entry for the new major.
+   Look for the `Compatibility` line that names the verified
+   emdash version range — confirm it covers your installed emdash.
+2. Bump the dependency range in `package.json`:
+   ```diff
+   -  "@aeptus/aexeo-emdash": "^0.1.0",
+   +  "@aeptus/aexeo-emdash": "^0.2.0",
+   ```
+3. `npm install`, build, deploy.
+
 The plugin's WASM is bundled with each version of the package, so
-`npm update` brings new rules along automatically. There's no
-separate sidecar to keep in sync (configured mode), no token to
-rotate, no Setup page to revisit.
+`npm update` / `npm install` brings new rules along automatically.
+There's no separate sidecar to keep in sync (configured mode), no
+token to rotate, no Setup page to revisit.
+
+**Verify after a plugin update:**
+
+1. Visit `/admin/plugins/aexeo-seogeo/findings` and click **Refresh**.
+   Toast should show non-zero rules sweeping. (A zero count *can*
+   be valid for a clean site, but if you previously had findings
+   and now have none, suspect the upgrade.)
+2. Save any document — `/findings` should auto-update for that
+   route's findings (the `content:afterSave` hook firing).
+
+### Updating emdash
+
+Updating emdash is the more dangerous direction because emdash
+controls the contracts the plugin depends on (PluginContext shape,
+hook signatures, Block Kit schemas, capability strings, etc.).
+Pre-flight before bumping:
+
+1. Look up the plugin version's tested emdash range in our
+   [CHANGELOG](./CHANGELOG.md). The latest plugin version's
+   `Compatibility` line says e.g. "tested against emdash 0.7.0
+   through 0.8.0." If the emdash version you want is **inside that
+   range**, the bump is safe. If it's **above the range**, treat it
+   as untested.
+2. If untested, scan the emdash release notes for breaking changes
+   in any of these areas (these are what the plugin touches):
+   - `PluginContext` shape (kv, http, content, log)
+   - Hook signatures (`content:afterSave`, etc.)
+   - Block Kit element schemas (banner variants, button styles,
+     table column formats)
+   - Capability validation strings (`read:content`, `network:fetch`)
+   - The `definePlugin` API
+   - The `createPlugin` / configured-plugin descriptor contract
+   If any of those changed, expect to bump the plugin too.
+3. Bump emdash:
+   ```bash
+   npm install emdash@<new-version>
+   ```
+4. Build and run locally first — never deploy directly to
+   production.
+5. Verify the plugin: same two checks as above (Refresh + save).
+
+If verification fails: roll emdash back
+(`npm install emdash@<previous-version>`), file an issue against
+this plugin describing the failure, and stay on the prior emdash
+version until a compatible plugin release ships.
+
+### When both need updating together
+
+Sometimes a plugin release will require an emdash bump (because we
+adopted a new emdash API). The plugin's CHANGELOG will say so:
+"Requires emdash >= X.Y.0." When that's the case:
+
+1. Update emdash first.
+2. Verify the existing plugin still works on the new emdash.
+3. Update the plugin.
+4. Verify again.
+
+Two separate deploys, two separate verification passes. This
+keeps the bisect clean if anything breaks.
+
+### Compatibility quick-reference
+
+The current verified pairing is recorded in
+[CHANGELOG.md](./CHANGELOG.md) at the top of each release entry.
+Treat anything outside that range as best-effort.
 
 ## Removing
 

package/dist/configured.d.ts

@@ -1,5 +1,12 @@
 export interface ConfiguredPluginOptions {
+    /**
+     * emdash collections the Refresh button sweeps. Comes through from
+     * the descriptor's `options` field — see `seogeoPlugin({ collections })`
+     * in src/index.ts. When undefined, falls back to DEFAULT_COLLECTIONS
+     * (`["posts", "pages"]`).
+     */
+    collections?: readonly string[];
 }
-export declare function createPlugin(_options?: ConfiguredPluginOptions): unknown;
+export declare function createPlugin(options?: ConfiguredPluginOptions): unknown;
 export default createPlugin;
 //# sourceMappingURL=configured.d.ts.map

package/dist/configured.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"configured.d.ts","sourceRoot":"","sources":["../src/configured.ts"],"names":[],"mappings":"AA4EA,MAAM,WAAW,uBAAuB;CAIvC;AAED,wBAAgB,YAAY,CAAC,QAAQ,GAAE,uBAA4B,GAAG,OAAO,CAiC5E;AAID,eAAe,YAAY,CAAC"}
+{"version":3,"file":"configured.d.ts","sourceRoot":"","sources":["../src/configured.ts"],"names":[],"mappings":"AA6EA,MAAM,WAAW,uBAAuB;IACtC;;;;;OAKG;IACH,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACjC;AAED,wBAAgB,YAAY,CAAC,OAAO,GAAE,uBAA4B,GAAG,OAAO,CAmD3E;AAID,eAAe,YAAY,CAAC"}

package/dist/configured.js

@@ -357,24 +357,33 @@ var inProcessEvaluator = async (documents) => {
     return { ok: false, reason: "wasm_error", detail };
   }
 };
-function createPlugin(_options = {}) {
+function createPlugin(options = {}) {
+  const collections = options.collections === void 0 ? DEFAULT_COLLECTIONS : [...options.collections];
   return definePlugin({
     id: "aexeo-seogeo",
     version: "0.0.1",
     capabilities: ["read:content"],
     hooks: {
+      // afterSave processes one saved document at a time — collections
+      // list isn't needed here. The hook always runs regardless of
+      // which collection the document came from.
       "content:afterSave": (event, ctx) => handleAfterSaveConfigured(event, ctx, inProcessEvaluator)
     },
     routes: {
-      admin: { handler: handleAdminRoute }
+      // The Refresh sweep (handleAdminRoute → handleRefresh) is the
+      // one consumer of `collections`. Bind the resolved list here so
+      // every request handles the same set without re-reading options.
+      admin: {
+        handler: (ctx) => handleAdminRoute(ctx, collections)
+      }
     },
     admin: {
       pages: [
-        // emdash's /admin/plugins/<id> root navigates to the plugin's
-        // "/" page — without it, clicking the plugin in the meta list
-        // produces a "Not Found". Alias "/" to the findings page so
-        // the entry-point lands somewhere useful.
-        { path: "/", label: "SEO findings" },
+        // The root URL `/admin/plugins/<id>/` routes through the same
+        // dispatcher (handlePageLoad treats "" and "findings" as
+        // aliases). Listing "/" alongside "/findings" here would create
+        // duplicate "SEO findings" sidebar entries — that was the
+        // visible 0.1.0 / 0.1.1 bug fixed in 0.1.2.
         { path: "/findings", label: "SEO findings" },
         { path: "/document", label: "Document SEO" }
       ],
@@ -385,7 +394,7 @@ function createPlugin(_options = {}) {
   });
 }
 var configured_default = createPlugin;
-async function handleAdminRoute(ctx) {
+async function handleAdminRoute(ctx, collections) {
   const body = ctx.input;
   if (body.type === "page_load") {
     return handlePageLoad(ctx, body.page);
@@ -395,7 +404,7 @@ async function handleAdminRoute(ctx) {
       return renderDocumentPanel(ctx, body.value);
     }
     if (body.action_id === "refresh_findings") {
-      return handleRefresh(ctx);
+      return handleRefresh(ctx, collections);
     }
     if (body.action_id.startsWith("filter:")) {
       return renderFindingsPage(ctx);
@@ -426,11 +435,12 @@ async function handlePageLoad(ctx, page) {
   }
   return notFound(page);
 }
-async function handleRefresh(ctx) {
+async function handleRefresh(ctx, collections) {
   let summary;
   try {
     summary = await evaluateAndPersistAll(ctx, {
-      evaluator: inProcessEvaluator
+      evaluator: inProcessEvaluator,
+      collections
     });
   } catch (err) {
     const detail = err instanceof Error ? err.message : String(err);

package/dist/index.d.ts

@@ -18,6 +18,27 @@ export interface ConfiguredPluginDescriptor {
     }[];
 }
 export interface SeogeoPluginOptions {
+    /**
+     * emdash collections the plugin sweeps when an admin clicks
+     * Refresh on the findings page. Order doesn't matter; the sweep
+     * iterates each collection sequentially and groups findings by
+     * document route. The per-document `content:afterSave` hook always
+     * runs regardless of this list — saving a document in any
+     * collection triggers an evaluation for that one document.
+     *
+     * Defaults to `["posts", "pages"]` (the slugs the
+     * `@emdash-cms/template-blog-cloudflare` template ships with).
+     * Override when your schema uses different collection slugs:
+     *
+     *     seogeoPlugin({ collections: ["posts", "guides", "products"] })
+     *
+     * Pointing this at a slug that doesn't exist in your schema is
+     * non-fatal: the bridge's `content.list` returns empty and the
+     * sweep records the missing collection in the Refresh summary's
+     * `errors` field. Safe to ship a superset for a project that may
+     * add collections later.
+     */
+    collections?: readonly string[];
 }
 export declare function seogeoPlugin(options?: SeogeoPluginOptions): ConfiguredPluginDescriptor;
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAqBA,OAAO,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AACrD,YAAY,EACV,eAAe,EACf,iBAAiB,EACjB,yBAAyB,EACzB,sBAAsB,GACvB,MAAM,cAAc,CAAC;AAWtB,MAAM,WAAW,0BAA0B;IACzC,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,UAAU,EAAE,SAAS;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACvD,YAAY,EAAE,SAAS;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CACxE;AAED,MAAM,WAAW,mBAAmB;CAGnC;AAED,wBAAgB,YAAY,CAC1B,OAAO,GAAE,mBAAwB,GAChC,0BAA0B,CA0B5B"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAqBA,OAAO,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AACrD,YAAY,EACV,eAAe,EACf,iBAAiB,EACjB,yBAAyB,EACzB,sBAAsB,GACvB,MAAM,cAAc,CAAC;AAWtB,MAAM,WAAW,0BAA0B;IACzC,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,UAAU,EAAE,SAAS;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACvD,YAAY,EAAE,SAAS;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CACxE;AAED,MAAM,WAAW,mBAAmB;IAClC;;;;;;;;;;;;;;;;;;;OAmBG;IACH,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACjC;AAED,wBAAgB,YAAY,CAC1B,OAAO,GAAE,mBAAwB,GAChC,0BAA0B,CAsC5B"}

package/dist/index.js

@@ -57,17 +57,27 @@ function seogeoPlugin(options = {}) {
     // time — must match the package.json `exports["./configured"]`
     // entry.
     entrypoint: "@aeptus/aexeo-emdash/configured",
-    options: { ...options },
+    // emdash's astro integration JSON-serializes `options` and emits
+    // an importer that does `createPlugin(<options>)` at boot.
+    // Anything we put here is what the runtime entry's createPlugin
+    // receives. Spread to a plain object so readonly arrays survive
+    // the structured-clone semantics of that codegen.
+    options: {
+      ...options.collections === void 0 ? {} : { collections: [...options.collections] }
+    },
     capabilities: [
       "read:content",
       "read:schema",
       "kv:seogeo-baselines"
     ],
+    // adminPages drives the admin sidebar — one nav entry per item.
+    // Don't list "/" alongside "/findings": both would render as
+    // duplicate "SEO findings" links in the sidebar (0.1.0 / 0.1.1
+    // shipped with this duplicate; fixed in 0.1.2). The root URL
+    // /admin/plugins/<id>/ still routes correctly because the
+    // dispatcher in src/configured.ts treats "" and "findings" as
+    // the same page.
     adminPages: [
-      // "/" alias is required so emdash's /admin/plugins/<id> root
-      // doesn't 404 — that page is where the meta /admin/plugins
-      // list links to when an operator clicks the plugin entry.
-      { path: "/", label: "SEO findings" },
       { path: "/findings", label: "SEO findings" },
       { path: "/document", label: "Document SEO" }
     ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aeptus/aexeo-emdash",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Aexeo seogeo SEO/GEO content evaluator as an emdash plugin",
   "license": "MIT",
   "author": "Aexeo",