release: v0.33.0 — plugin contract bundle + install error surfacing (#57)

Bumps version to 0.33.0 so the plugin nutri (which requires this version)
can install. Bundles the five plugin-contract PRs (#52→#56) merged today
into a single release. Plus a UX fix on the install wizard so 409s say why
they conflicted.

The fix
- lib/api.ts buildError now falls back to data.conflicts[0] when the
  standard error/message fields are absent. The plugin preview endpoint
  returns {conflicts: string[], manifest, ...} on 409 — without this fix
  the wizard showed only "409 CONFLICT" with the actual reason hidden.
- PluginInstallModal: conflicts type was Record<string, unknown>, backend
  always returned string[]; the JSON.keys() coercion produced index strings.
  Now typed as string[] and rendered as a list.

Tested
- Frontend tsc --noEmit clean
- Plugin nutri 200 pytest still pass after the 11 `# nosec B603` markers
  added to subprocess.run calls (false positives from regex security scan —
  all calls use list args, no shell=True)

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: DavidsonGomes

CHANGELOG.md

@@ -5,6 +5,27 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.33.0] - 2026-04-25
+
+Plugin contract release. Five PRs merged in one day to unblock the EvoNexus Plugin Nutri (and any future plugin needing per-endpoint role enforcement, public token-bound portals, or safe uninstall). Plus a UX fix so `409 CONFLICT` from plugin install actually says *why* it conflicted.
+
+### Added
+
+- **`requires_role` on `PluginWritableResource`** (PR #55) — plugins can declare a list of roles allowed on each writable endpoint. The host returns `403` when `current_user.role` is not in the list. `'admin'` always passes (super-user override). Backwards compatible: resources without the field accept any authenticated user.
+- **Auto-injected readonly bind params** (PR #55) — every `readonly_data` query receives `:current_user_id` and `:current_user_role` server-side. Plugins reference them directly in SQL for scoping (`WHERE primary_nutritionist_id = :current_user_id`). Both names are reserved — clients that try to spoof them via `?current_user_id=...` get `400`.
+- **`public_pages` capability** (PR #53) — token-bound public portals at `/p/{slug}/{route_prefix}/{token}`. Token validated against a plugin-declared `token_source.column`. CSP, rate limit, and security headers applied. Read-only `readonly_data` queries can be exposed to the portal via `public_via` + `bind_token_param`.
+- **HTML shell content negotiation** (PR #56) — when a request includes `text/html` in `Accept`, the host renders a minimal HTML shell that loads the plugin bundle as a module and instantiates the declared custom element with `data-token`. Programmatic clients (`Accept: application/javascript`, default `*/*`) keep getting the raw bundle. Plugins ship a single JS bundle and get a working browser experience for free.
+- **`safe_uninstall` capability** (PR #54) — three-step uninstall wizard with `preserved_tables` (renamed to `_orphan_{slug}_*` instead of dropped), pre-uninstall hook (sandboxed: read-only DB, no `BRAIN_REPO_MASTER_KEY`), and required user confirmation (checkbox + typed phrase + ZIP password). Reinstall verifies SHA256 and restores access to preserved data.
+- **Rate limit + security headers** (PR #52) — `flask-limiter` with in-memory storage on the public share endpoint and any future `/p/...` route. Five security headers applied to public responses (`Referrer-Policy`, `Cache-Control: no-store`, HSTS, `X-Content-Type-Options`, `Pragma`).
+
+### Fixed
+
+- **Plugin install wizard now shows the actual reason for `409 CONFLICT`.** The frontend was treating any 4xx as an opaque error string. Now `buildError` in `lib/api.ts` falls back to `data.conflicts[0]` when the standard `error`/`message` fields are absent (which is the case for the plugin preview endpoint), so a version mismatch shows up as `"409 CONFLICT: Plugin 'nutri' requires EvoNexus >= 0.33.0, but installed version is 0.32.3."` instead of just `"409 CONFLICT"`. `PluginInstallModal` also fixes the type of `conflicts` (was `Record<string, unknown>`, the backend always returned `string[]`) and renders each conflict as a list item.
+
+### Compat
+
+- All existing plugins (PM Essentials, etc.) work unchanged. New manifest fields default to absent / `None` and the auto-injected bind params are silently ignored if the SQL doesn't reference them. The `409` body shape for plugin install was already `{conflicts: [...], manifest, ...}` — only the frontend's interpretation changed.
+
 ## [0.32.3] - 2026-04-25
 
 Patch release fixing a long-standing Workspace UI bug where folders refused to open and the dev console flooded with `400 Path is a directory` requests, plus a small UX win on the file share dialog (reuse existing share links instead of generating a new token every time). Also includes the upstream PR #51 (private-repo plugin update flow + ClickUp webhook compat + DetachedInstanceError).

dashboard/frontend/src/components/PluginInstallModal.tsx

@@ -7,7 +7,10 @@ import SecurityScanSection, { type ScanVerdict, type ScanResult } from './Securi
 interface PreviewResult {
   manifest: Record<string, unknown>
   warnings: string[]
-  conflicts?: Record<string, unknown>
+  // Backend returns conflicts as a list of human-readable strings (not a dict).
+  // See plugin_loader.PluginInstaller.preview() — each blocker is a string
+  // appended to result["conflicts"].
+  conflicts?: string[]
 }
 
 interface Props {
@@ -140,7 +143,9 @@ export default function PluginInstallModal({ onClose, onInstalled }: Props) {
 
   const manifest = preview?.manifest ?? {}
   const warnings = preview?.warnings ?? []
-  const conflicts = preview?.conflicts ? Object.keys(preview.conflicts) : []
+  const conflicts: string[] = Array.isArray(preview?.conflicts)
+    ? (preview!.conflicts as string[]).filter((c): c is string => typeof c === 'string' && c.length > 0)
+    : []
 
   // Install button is amber for WARN, normal green otherwise
   const installBtnClass =
@@ -338,7 +343,11 @@ export default function PluginInstallModal({ onClose, onInstalled }: Props) {
                   <p className="text-xs font-medium text-red-400 mb-1 flex items-center gap-1.5">
                     <AlertTriangle size={12} /> {t('plugins.conflicts')}
                   </p>
-                  <p className="text-xs text-red-300/80">{conflicts.join(', ')}</p>
+                  <ul className="space-y-0.5 list-disc list-inside">
+                    {conflicts.map((c, i) => (
+                      <li key={i} className="text-xs text-red-300/80">{c}</li>
+                    ))}
+                  </ul>
                 </div>
               )}
 

dashboard/frontend/src/lib/api.ts

@@ -15,7 +15,20 @@ async function buildError(res: Response): Promise<Error> {
   let detail = ''
   try {
     const data = await res.clone().json()
-    detail = data?.error || data?.description || data?.message || ''
+    // Try common error shapes first, then plugin-preview-shaped responses
+    // (`{conflicts: [...], manifest, ...}`). Without this, plugin install
+    // 409s surfaced as "409 CONFLICT" with no hint at the actual reason
+    // (e.g. version mismatch).
+    detail =
+      data?.error ||
+      data?.description ||
+      data?.message ||
+      (Array.isArray(data?.conflicts) && data.conflicts.length > 0
+        ? data.conflicts.join(' • ')
+        : '') ||
+      (Array.isArray(data?.details) && data.details.length > 0
+        ? data.details.join(' • ')
+        : '')
   } catch {
     try {
       const text = await res.text()

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "evo-nexus"
-version = "0.32.3"
+version = "0.33.0"
 description = "Unofficial open source toolkit for Claude Code — AI-powered business operating system"
 requires-python = ">=3.10"
 dependencies = [