@aeptus/aexeo-emdash 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,45 @@
+# Changelog
+
+All notable changes to `@aeptus/aexeo-emdash` are listed here.
+The format follows [Keep a Changelog](https://keepachangelog.com/),
+and the project follows [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-04-28
+
+First public release.
+
+### Added
+
+- `seogeoPlugin()` factory for **configured mode** — the recommended
+  install path for first-party emdash sites. Plugin runs in-process
+  inside the host Worker. No sidecar deploy, no auth token, no admin
+  Setup page.
+- `seogeoPluginSandboxed({ evaluatorHost })` factory for **sandboxed
+  mode** — preserved for future third-party-deploy scenarios where
+  the plugin code shouldn't have full host access. Requires a
+  separately-deployed sidecar Worker (template at
+  `seogeo-crawl-worker` in the source repo).
+- Block Kit admin pages: findings table, per-document panel,
+  intelligence-score dashboard widget. Refresh button on the
+  findings page sweeps every document in the configured collections.
+- `content:afterSave` hook (configured mode only): saves trigger an
+  automatic re-evaluation of the changed document and update the
+  findings table without manual intervention.
+- WASM-backed evaluator powered by the `aexeo-emdash-bridge` Rust
+  crate (same engine as the seogeo CLI). Compiles via the consumer's
+  Vite/Wrangler chain — `vite-plugin-wasm` is a peer-side runtime
+  dependency for Vite-driven Cloudflare deploys.
+
+### 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`.
+
+[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

package/INSTALL.md

@@ -0,0 +1,289 @@
+# Installing `@aeptus/aexeo-emdash`
+
+This package adds Aexeo's seogeo SEO/GEO content evaluator to an emdash
+site. Findings show up as a Block Kit admin page; a sidebar widget
+shows the site's current intelligence score; saves auto-evaluate the
+changed document.
+
+## Two install paths
+
+The package exports two factories:
+
+- **`seogeoPlugin()`** — **configured mode** (recommended). Plugin
+  runs in-process inside the host emdash Worker. No separate
+  deployment, no auth token, no admin Setup page. Use this for
+  first-party emdash sites.
+- **`seogeoPluginSandboxed({ evaluatorHost })`** — **sandboxed
+  mode**. Plugin runs inside emdash's Worker Loader isolate; WASM
+  evaluation runs in a separate sidecar Worker the operator
+  deploys. Use this only when a third party hosts emdash and
+  doesn't trust the plugin code with full host access.
+
+Configured mode is what most installs should pick. The instructions
+below cover that path. Sandboxed mode is documented at the bottom for
+when it's actually needed.
+
+## Configured mode (recommended)
+
+### Prerequisites
+
+- An emdash site running on the **Cloudflare** adapter
+  (`@astrojs/cloudflare` + `@emdash-cms/cloudflare`'s `sandbox()`
+  runner is fine — sandboxed plugins use Worker Loader, configured
+  plugins don't, but both adapters import cleanly).
+- emdash 0.7.0 or later as a peer dependency.
+
+### Install
+
+```bash
+npm install @aeptus/aexeo-emdash vite-plugin-wasm
+```
+
+`vite-plugin-wasm` is required because Vite's defaults treat `.wasm`
+imports as static-asset URLs, but Cloudflare Workers can only run
+WASM as precompiled `WebAssembly.Module` instances. The plugin
+bridges the two; without it, the seogeo plugin's first call throws
+"WASM module did not resolve to a WebAssembly.Module."
+
+> **If installing from a private git remote or as a vendored
+> directory** — see the "Alternative install sources" section at the
+> end. The result is the same, just the dependency line differs.
+
+### Wire into `astro.config.mjs`
+
+```js
+import cloudflare from "@astrojs/cloudflare";
+import { d1, r2 } from "@emdash-cms/cloudflare";
+import { seogeoPlugin } from "@aeptus/aexeo-emdash";
+import { defineConfig } from "astro/config";
+import emdash from "emdash/astro";
+import wasm from "vite-plugin-wasm";
+
+export default defineConfig({
+  output: "server",
+  adapter: cloudflare(),
+  vite: {
+    // Required: makes `import x from "./foo.wasm"` resolve to a
+    // precompiled WebAssembly.Module. Cloudflare Workers /
+    // workerd disallow runtime WebAssembly.instantiate from raw
+    // bytes, so the bundler has to do the compilation.
+    plugins: [wasm()],
+    // The seogeo plugin's WASM import confuses Vite's dep
+    // optimizer when it tries to pre-bundle the package.
+    optimizeDeps: { exclude: ["@aeptus/aexeo-emdash"] },
+  },
+  integrations: [
+    emdash({
+      database: d1({ binding: "DB" }),
+      storage: r2({ binding: "MEDIA" }),
+      plugins: [seogeoPlugin()],
+    }),
+  ],
+});
+```
+
+That's it for code. No environment variables, no secrets to manage,
+no sidecar to deploy.
+
+### Verify
+
+1. Start the dev server: `npm run dev`.
+2. The emdash startup log doesn't print a special line for configured
+   plugins (only sandboxed ones get a "Loaded sandboxed plugin..."
+   line). Instead, navigate to:
+
+   ```
+   http://localhost:4321/_emdash/admin/plugins
+   ```
+
+   The seogeo plugin will appear in the list. Click it.
+
+3. The findings page renders with a Refresh button. Click **Refresh**
+   — toast says "Refreshed N routes (M findings across K documents)"
+   and the table populates.
+
+4. Save a document: the `content:afterSave` hook auto-evaluates that
+   one document; refresh the findings page and that route's findings
+   are updated. (The dashboard widget also picks up the new score.)
+
+### Production deploy
+
+Run your usual Astro/Cloudflare deploy: `npm run build && wrangler
+deploy` (or whatever your CI does). The same `vite-plugin-wasm` and
+`optimizeDeps.exclude` lines work for production builds — the plugin
+ships its WASM as a separate `.wasm` file under
+`node_modules/@aeptus/aexeo-emdash/wasm/` which Wrangler
+compiles into the deployed Worker artifact.
+
+## Updating
+
+```bash
+npm update @aeptus/aexeo-emdash
+npm run build && <your deploy command>
+```
+
+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.
+
+## Removing
+
+Delete the dependency, the import, and the `seogeoPlugin()` line in
+`integrations:[emdash({plugins:[...]})]`. The KV keys the plugin
+wrote remain in your KV namespace — purge with
+`wrangler kv:key delete --prefix=findings:` and
+`wrangler kv:key delete --prefix=document:` if you want a clean
+removal.
+
+## Sandboxed mode (future external deploys)
+
+If you're shipping this plugin to a third-party emdash site whose
+operator should NOT have the plugin code running in their host
+Worker process, switch to sandboxed mode. This requires deploying a
+separate sidecar Worker that runs the WASM evaluator.
+
+Trade-offs vs. configured mode:
+
+- **Pro**: V8 isolate boundary; capability + allowedHosts enforcement
+  prevents the plugin from ever reading host state directly.
+- **Con**: separate sidecar Worker to deploy and maintain; an
+  EVAL_TOKEN to rotate; a Setup admin page to configure. The
+  `content:afterSave` hook is also non-functional in emdash 0.7.x's
+  sandbox (post-response bridge invalidation — known upstream issue);
+  evaluation is manual-Refresh-only.
+
+```js
+// astro.config.mjs (sandboxed mode)
+import { sandbox } from "@emdash-cms/cloudflare";
+import { seogeoPluginSandboxed } from "@aeptus/aexeo-emdash";
+
+emdash({
+  database: d1({ binding: "DB" }),
+  storage: r2({ binding: "MEDIA" }),
+  sandboxed: [
+    seogeoPluginSandboxed({
+      // Public host of the deployed sidecar Worker.
+      evaluatorHost: "seogeo-crawl-worker.<subdomain>.workers.dev",
+    }),
+  ],
+  sandboxRunner: sandbox(),
+});
+```
+
+The sidecar Worker template lives at `packages/seogeo-crawl-worker/`
+in this repo. Per-site deploy:
+
+```bash
+cd seogeo-crawl-worker
+# Edit wrangler.toml: name, R2 bucket name, SITE_URL
+npx wrangler login
+npx wrangler r2 bucket create <bucket-name>
+npx wrangler deploy
+echo "$(openssl rand -hex 32)" | npx wrangler secret put EVAL_TOKEN
+```
+
+Then in the admin UI, visit
+`/admin/plugins/aexeo-seogeo/setup` and paste the deployed URL +
+the same token.
+
+## Alternative install sources
+
+Public npm is the recommended path. If your install context can't
+reach the npm registry, two fallbacks:
+
+**Git URL** (works without npm registry access, requires GitHub
+SSH access to the source repo):
+
+```jsonc
+"dependencies": {
+  "@aeptus/aexeo-emdash":
+    "git+ssh://git@github.com/schiste/Aexeo.git#<commit-sha>:packages/aexeo-emdash"
+}
+```
+
+Pin to a commit SHA, not a branch. Update by changing the SHA.
+
+**Vendored copy** (no git access required):
+
+Copy `dist/`, `wasm/`, and `package.json` from this repo into your
+project at e.g. `vendor/aexeo-emdash/`, then:
+
+```jsonc
+"dependencies": {
+  "@aeptus/aexeo-emdash": "file:./vendor/aexeo-emdash"
+}
+```
+
+Update by re-copying the directory. Vendored installs lose npm's
+update tracking, so this is the heaviest of the three options
+operationally.
+
+## Troubleshooting
+
+**`Wasm code generation disallowed by embedder` at first Refresh.**
+The bundle is trying to instantiate WASM from raw bytes at runtime,
+which Cloudflare Workers reject. Confirm `vite-plugin-wasm` is
+installed and in the `vite.plugins` array of `astro.config.mjs`. If
+present, double-check the package version is recent (≥ the version
+that switched to direct .wasm imports — see git log for `Switch
+configured-mode WASM from inlined bytes to direct .wasm import`).
+
+**`seogeo: WASM module did not resolve to a WebAssembly.Module`**
+The bundler resolved the .wasm import but produced something other
+than a Module (URL string, Uint8Array). Same fix as above: ensure
+`vite-plugin-wasm` is loaded.
+
+**`Cannot read properties of undefined (reading 'kv')` on Refresh.**
+Older plugin version where the configured-mode handler used the
+sandboxed two-arg ctx shape. Update; it's fixed in the version with
+`Switch configured-mode WASM from inlined bytes to direct .wasm
+import` in the commit log.
+
+**`/admin/plugins` doesn't list seogeo, but `/findings` works.** The
+emdash version's plugins meta page may filter out plugins without a
+`/` adminPage entry. The package declares one explicitly; if you see
+this on a recent version, it's an emdash regression — file upstream.
+
+**`Refresh issues: posts: TypeError: ...`** during a sweep. The
+adapter hit a content item shape it didn't expect (a custom
+collection field, an unusual schema). Open an issue with the
+collection's slug + the failing field; we'll add defensive handling.
+
+**Plugin doesn't appear in admin sidebar at all.** Confirm the
+emdash adapter is `@astrojs/cloudflare`'s `cloudflare()`. The plugin
+relies on Cloudflare-specific APIs and won't load (silently) on the
+Node adapter.
+
+## What the plugin actually does
+
+- **Findings page** (`/_emdash/admin/plugins/aexeo-seogeo/findings`):
+  Block Kit table of every rule violation across the site. Filter by
+  severity. Click a route in the picker to drill into per-document
+  findings.
+- **Document panel** (`/document`): the same findings, scoped to one
+  document.
+- **Score widget** (dashboard): top-line intelligence score across
+  citation, truth, answer-pack, external-trust dimensions. Banner
+  appears below 60.
+- **Refresh button** on the findings page: re-evaluate every
+  document in the configured collections (`posts`, `pages` by
+  default). Writes findings to KV under `findings:<route>` and the
+  evaluated document under `document:<route>`.
+- **Auto-evaluate on save**: emdash's `content:afterSave` hook fires
+  for each save, re-evaluates that one document, and updates its
+  KV findings entry. The dashboard widget reflects the new score on
+  the next page load.
+
+## Architecture in one paragraph
+
+The plugin runs in-process inside the host emdash Worker. Saves
+trigger emdash's `content:afterSave` hook, which adapts the saved
+content to the bridge's wire format and runs the WASM evaluator
+inline. Findings are stored in the host's plugin KV (the
+`PluginContext.kv` accessor). The Refresh button does the same thing
+but for every document in every configured collection. The WASM
+itself is the same `aexeo-emdash-bridge` Rust crate that powers the
+seogeo CLI; it's compiled to WebAssembly via wasm-pack and imported
+by the host's bundler (Vite + `vite-plugin-wasm`). No separate
+service, no sidecar, no auth token.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aexeo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,78 @@
+# @aeptus/aexeo-emdash
+
+Aexeo's seogeo SEO/GEO content evaluator as an emdash plugin.
+
+Adds a Findings admin page, per-document panel, and dashboard
+intelligence-score widget to an emdash site. Saves auto-evaluate the
+changed document; the Refresh button re-evaluates the whole site.
+
+## Install
+
+```bash
+npm install @aeptus/aexeo-emdash vite-plugin-wasm
+```
+
+```js
+// astro.config.mjs
+import { seogeoPlugin } from "@aeptus/aexeo-emdash";
+import wasm from "vite-plugin-wasm";
+
+export default defineConfig({
+  vite: {
+    plugins: [wasm()],
+    optimizeDeps: { exclude: ["@aeptus/aexeo-emdash"] },
+  },
+  integrations: [
+    emdash({
+      database: d1({ binding: "DB" }),
+      storage: r2({ binding: "MEDIA" }),
+      plugins: [seogeoPlugin()],
+    }),
+  ],
+});
+```
+
+That's it. No environment variables, no auth tokens, no admin Setup
+page, no separate sidecar to deploy.
+
+For the full install runbook, sandboxed-mode alternative, and
+troubleshooting list, see [INSTALL.md](./INSTALL.md).
+
+## What it does
+
+- **Findings page** at `/_emdash/admin/plugins/aexeo-seogeo/findings`:
+  rule violations across the site, filterable by severity.
+- **Document panel** at `/document`: findings scoped to one document.
+- **Dashboard widget**: top-line intelligence score (citation, truth,
+  answer-pack, external-trust dimensions). Banner appears below 60.
+- **Refresh button**: re-evaluate every document in the configured
+  collections (`posts`, `pages` by default).
+- **Auto-evaluate on save**: emdash's `content:afterSave` hook fires,
+  re-evaluates the saved document, updates the findings table.
+
+## Compatibility
+
+- emdash `>= 0.7.0` (peer dep)
+- Cloudflare Workers via `@astrojs/cloudflare`. The plugin uses
+  Cloudflare-specific APIs and silently no-ops on the Node adapter.
+- WASM eval ships with the package; the consumer's Vite/Wrangler
+  bundler handles compilation at build time. `vite-plugin-wasm` is a
+  hard requirement on the consumer side.
+
+## Two factories
+
+The package exports two factories for different trust contexts:
+
+- `seogeoPlugin()` — **configured mode** (recommended). In-process
+  plugin. Use for first-party emdash sites.
+- `seogeoPluginSandboxed({ evaluatorHost })` — **sandboxed mode**.
+  Requires a separately-deployed sidecar Worker. Use only when
+  shipping to third-party emdash sites that shouldn't trust the
+  plugin code with full host access.
+
+See [INSTALL.md](./INSTALL.md#sandboxed-mode-future-external-deploys)
+for the sandboxed setup runbook.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/dist/adapter.d.ts

@@ -0,0 +1,16 @@
+import type { EmdashDocument } from "./types.js";
+export interface EmdashContentItem {
+    id: string;
+    type: string;
+    slug: string | null;
+    status: string;
+    locale: string | null;
+    data: Record<string, unknown>;
+    seo?: {
+        title?: string | null;
+        description?: string | null;
+        canonical?: string | null;
+    };
+}
+export declare function contentItemToEmdashDocument(content: EmdashContentItem): EmdashDocument;
+//# sourceMappingURL=adapter.d.ts.map

package/dist/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAqB,MAAM,YAAY,CAAC;AAmBpE,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,GAAG,CAAC,EAAE;QACJ,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QACtB,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAC5B,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;KAC3B,CAAC;CACH;AAED,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,iBAAiB,GACzB,cAAc,CAyBhB"}

package/dist/configured.d.ts

@@ -0,0 +1,5 @@
+export interface ConfiguredPluginOptions {
+}
+export declare function createPlugin(_options?: ConfiguredPluginOptions): unknown;
+export default createPlugin;
+//# sourceMappingURL=configured.d.ts.map

package/dist/configured.d.ts.map

@@ -0,0 +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"}