@enfyra/mcp-server 0.0.111 → 0.0.113

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enfyra/mcp-server",
-  "version": "0.0.111",
+  "version": "0.0.113",
   "description": "MCP server for Enfyra - manage Enfyra instances from MCP-compatible coding tools",
   "type": "module",
   "license": "MIT",

package/src/lib/mcp-examples.js

@@ -1531,7 +1531,7 @@ ensure_page_extension({
   name: "ReportsPage",
   description: "Reports dashboard",
   menuId: "<created-menu-id>",
-  code: "<template><section class=\\"min-h-full w-full space-y-4\\"><div class=\\"grid gap-4 md:grid-cols-3\\"><UCard><p class=\\"text-sm text-muted\\">Total</p><p class=\\"mt-2 text-2xl font-semibold\\">0</p></UCard></div></section></template><script setup>const { registerPageHeader } = usePageHeaderRegistry(); const { register: registerHeaderActions } = useHeaderActionRegistry(); registerPageHeader({ title: 'Reports', description: 'Operational report overview.', leadingIcon: 'lucide:bar-chart-3', gradient: 'cyan', variant: 'minimal' }); registerHeaderActions([{ id: 'refresh-reports', label: 'Refresh', icon: 'lucide:refresh-cw', onClick: () => {}, order: 0 }])</script>",
+  code: "<template><section class=\\"min-h-full w-full space-y-4\\"><div class=\\"grid gap-4 md:grid-cols-2 xl:grid-cols-3\\"><article class=\\"eapp-identity-surface rounded-[var(--radius-panel)] border p-4\\"><div class=\\"flex items-start justify-between gap-3\\"><div><p class=\\"text-sm font-medium text-[var(--text-tertiary)]\\">Total</p><p class=\\"mt-2 text-2xl font-semibold text-[var(--text-primary)]\\">0</p></div><span class=\\"eapp-identity-soft rounded-[var(--radius-pill)] px-2 py-0.5 text-xs font-semibold\\">Current</span></div></article></div></section></template><script setup>const { registerPageHeader } = usePageHeaderRegistry(); const { register: registerHeaderActions } = useHeaderActionRegistry(); registerPageHeader({ title: 'Reports', description: 'Operational report overview.', leadingIcon: 'lucide:bar-chart-3', gradient: 'none', variant: 'minimal' }); registerHeaderActions([{ id: 'refresh-reports', label: 'Refresh', icon: 'lucide:refresh-cw', color: 'neutral', variant: 'outline', onClick: () => {}, order: 80 }])</script>",
   isEnabled: true
 })`,
         notes: [
@@ -1546,7 +1546,12 @@ ensure_page_extension({
           'Put page-level actions in useHeaderActionRegistry or useSubHeaderActionRegistry, destructure register first, then call it with one action or an array.',
           'Page extensions should be full-bleed by default and responsive from the first version.',
           'The extension root is already inside Enfyra admin page main; do not add root-level page padding.',
-          'Use existing eApp theme variables for panels, rows, badges, borders, and text. Pair border/divide utilities with border-[var(--border-default)] or divide-[var(--border-default)] so light and dark themes stay consistent.',
+          'Use existing eApp theme variables for panels, rows, badges, borders, controls, radius, and text. Pair border/divide utilities with border-[var(--border-default)] or divide-[var(--border-default)] so light and dark themes stay consistent.',
+          'Treat primary color as runtime-configurable by the app color picker. For Nuxt UI components, choose color="primary" by semantic intent; for custom extension blocks, choose eapp-identity-surface for larger tinted blocks, eapp-identity-soft for compact chips, eapp-identity-solid for fills, or eapp-identity-text for icons by intent instead of choosing Tailwind color utilities.',
+          'Use PageHeader gradient: "none" for generated operational pages unless the user explicitly asks for a decorative page accent; do not hardcode cyan/violet/purple/blue/green gradients.',
+          'For general card grids inside the shell, use md:grid-cols-2 xl:grid-cols-3 instead of lg:grid-cols-3 because the desktop sidebar leaves tablet-width content at 1024px.',
+          'Do not use Nuxt UI neutral semantic classes such as bg-default, text-muted, text-dimmed, border-default, or divide-default inside extension code; use eApp tokens/classes.',
+          'Do not pass ui.content: "surface-card" to UModal/CommonModal; modal content uses the app modal surface and caller content classes should only append z-index or width.',
           'Do not inject global CSS, create theme guards, redefine the app palette, or solve one extension by overriding the whole app shell.',
           'Keep list selection local and fetch detail rows only; do not refetch the whole list after a row click unless the list data changed.',
           'Page extension paths are admin app UI routes. Do not verify them with test_rest_endpoint against ENFYRA_API_URL unless inspect_route shows an API route with the same path.',
@@ -1558,16 +1563,19 @@ ensure_page_extension({
         code: `// Create reusable/bulky sections as widget extension records first.
 const reportStatusWidgetCode = \`
 <template>
-  <section class="rounded-xl border border-default bg-default p-4">
+  <section class="surface-card p-4">
     <div class="flex items-start justify-between gap-3">
       <div>
-        <p class="text-sm text-muted">Total reports</p>
-        <p class="mt-2 text-2xl font-semibold">{{ total }}</p>
-        <p class="mt-1 text-xs text-muted">{{ latestLabel }}</p>
+        <p class="text-sm font-medium text-[var(--text-tertiary)]">Total reports</p>
+        <p class="mt-2 text-2xl font-semibold text-[var(--text-primary)]">{{ total }}</p>
+        <p class="mt-1 text-xs text-[var(--text-tertiary)]">{{ latestLabel }}</p>
       </div>
       <UButton type="button" color="neutral" variant="outline" @click.stop.prevent="emit('refresh')">Refresh</UButton>
     </div>
-    <UButton v-if="hasLatest" type="button" class="mt-3" color="primary" variant="soft" @click.stop.prevent="openLatest">Open latest</UButton>
+    <div class="mt-3 h-1.5 overflow-hidden rounded-[var(--radius-pill)] bg-[var(--surface-muted)]">
+      <div class="eapp-identity-solid h-full" :style="{ width: progressWidth }"></div>
+    </div>
+    <UButton v-if="hasLatest" type="button" class="mt-3" color="primary" variant="solid" @click.stop.prevent="openLatest">Open latest</UButton>
   </section>
 </template>
 
@@ -1580,6 +1588,7 @@ const props = defineProps({
 const emit = defineEmits(['refresh'])
 const hasLatest = computed(() => props.rows.length > 0)
 const latestLabel = computed(() => hasLatest.value ? 'Latest: ' + (props.rows[0]?.title || props.rows[0]?.id || 'Untitled') : 'No reports yet')
+const progressWidth = computed(() => hasLatest.value ? '100%' : '0%')
 function openLatest() {
   if (typeof props.openDetails === 'function' && props.rows[0]) props.openDetails(props.rows[0])
 }
@@ -1597,7 +1606,7 @@ ensure_widget_extension({
 ensure_page_extension({
   name: "ReportsPage",
   menuId: "<reports-menu-id>",
-  code: "<template><section class=\\"min-h-full w-full space-y-4\\"><Widget :id=\\"<report-status-widget-id>\\" :total=\\"totalReports\\" :rows=\\"reportRows\\" :open-details=\\"openReportDetails\\" @refresh=\\"refresh\\" /><Widget :id=\\"<report-table-widget-id>\\" :rows=\\"reportRows\\" @refresh=\\"refresh\\" /></section></template><script setup>const { registerPageHeader } = usePageHeaderRegistry(); registerPageHeader({ title: 'Reports', description: 'Operational report overview.', leadingIcon: 'lucide:bar-chart-3', gradient: 'cyan', variant: 'minimal' }); const totalReports = ref(0); const reportRows = ref([]); function refresh() {} function openReportDetails(row) { navigateTo('/data/report?filter=' + encodeURIComponent(JSON.stringify({ id: { _eq: row.id } }))) }</script>",
+  code: "<template><section class=\\"min-h-full w-full space-y-4\\"><Widget :id=\\"<report-status-widget-id>\\" :total=\\"totalReports\\" :rows=\\"reportRows\\" :open-details=\\"openReportDetails\\" @refresh=\\"refresh\\" /><Widget :id=\\"<report-table-widget-id>\\" :rows=\\"reportRows\\" @refresh=\\"refresh\\" /></section></template><script setup>const { registerPageHeader } = usePageHeaderRegistry(); registerPageHeader({ title: 'Reports', description: 'Operational report overview.', leadingIcon: 'lucide:bar-chart-3', gradient: 'none', variant: 'minimal' }); const totalReports = ref(0); const reportRows = ref([]); function refresh() {} function openReportDetails(row) { navigateTo('/data/report?filter=' + encodeURIComponent(JSON.stringify({ id: { _eq: row.id } }))) }</script>",
   isEnabled: true
 })`,
         notes: [
@@ -1738,7 +1747,7 @@ registerPageHeader({
   title: 'Report detail',
   description: 'Review status, schedule, and delivery history.',
   leadingIcon: 'lucide:file-text',
-  gradient: 'cyan',
+  gradient: 'none',
   variant: 'minimal'
 })
 
@@ -1766,8 +1775,8 @@ registerHeaderActions([
     id: 'refresh-report',
     label: 'Refresh',
     icon: 'lucide:refresh-cw',
-    color: 'primary',
-    variant: 'solid',
+    color: 'neutral',
+    variant: 'outline',
     order: 2,
     onClick: refresh
   }
@@ -1775,9 +1784,10 @@ registerHeaderActions([
 </script>`,
         notes: [
           'Use PageHeader for the title strip; do not render a duplicate header inside extension body.',
+          'Use gradient: "none" for generated operational pages; hardcoded named gradients are decorative and should be explicit user intent.',
           'Back/navigation actions should be neutral ghost so they read as navigation, not a primary operation.',
           'Visible secondary operations should be neutral outline; soft is only for low-emphasis chrome actions.',
-          'The main page action should be primary solid.',
+          'The main page mutation action should be primary solid; refresh is neutral outline unless refresh is the actual primary workflow.',
           'Do not choose soft only because it looks acceptable in dark mode; light mode must remain clear too.',
         ],
       },

package/src/lib/platform-operation-tools.js

@@ -297,18 +297,41 @@ function getExtensionThemeContract() {
       'The extension is already mounted inside the Enfyra app shell. Do not add a duplicate page header, centered page wrapper, or root-level page padding.',
       'Page extensions should be full-bleed, responsive, and split large operations into focused pages or UTabs.',
       'Use usePageHeaderRegistry for the shell title and useHeaderActionRegistry/useSubHeaderActionRegistry for page actions.',
+      'For detail/form workflows that should stay left-aligned with empty space on the right, wrap the body in eapp-page-constrained; use eapp-page-constrained-wide only when the workflow genuinely needs more width.',
+      'Card/list grids inside the default shell must account for the 280px desktop sidebar. Do not switch general card grids to three columns at lg; use md:grid-cols-2 xl:grid-cols-3 unless a local container proves three columns have enough width.',
     ],
     theme: [
-      'Use existing eApp theme variables/classes, not hardcoded light or dark colors.',
+      'Use existing eApp theme variables/classes, not hardcoded light or dark colors. The app theme source of truth is CSS variables, including --brand-*, --surface-*, --card-*, --control-*, --action-*, --badge-*, --radius-*, --border-*, and --text-*.',
+      'Primary color is runtime-configurable through the app color picker. For Nuxt UI components, choose color="primary" by semantic intent and let the app map it through the primary contract; do not choose a concrete palette. For custom extension blocks, choose semantic intent classes, not colors: use eapp-identity-surface for larger entity/feature blocks, tiles, or cards that need a tinted/dark surface matching the shell; add eapp-identity-surface-hover when that block is clickable. Use eapp-identity-soft for compact selected entity chips, pills, small icon tiles, and identity callouts; add eapp-identity-soft-hover when compact surfaces are clickable; use eapp-identity-solid only for primary identity fills; use eapp-identity-text for identity icons or inline text. The eapp-accent-* aliases are still available for the same runtime-primary intent, but eapp-identity-* is preferred when the UI element represents an entity or feature identity.',
+      'Nuxt UI secondary is still a valid semantic color when the product intentionally wants a secondary action or state. Do not use color="secondary", from-secondary-*, bg-secondary-*, text-secondary-*, or cyan/purple/green palette utilities merely to approximate an entity accent; use eapp-identity-* and let the app decide the color.',
+      'Do not make custom extension blocks with Tailwind palette utilities or raw primary utilities such as text-primary, bg-primary/10, border-primary, ring-primary/20, from-cyan-*, text-violet-*, bg-green-*, or dark:bg-zinc-950. The app owns how eapp-identity-* and eapp-accent-* map to the active color picker value.',
+      'Use UButton color="primary" only for the single main action for the current scope. Refresh, back, navigation, filters, and secondary actions should be neutral variants unless they are the main mutation.',
+      'PageHeader gradient must be "none" for generated operational extensions unless the user explicitly asks for a decorative page accent. Do not hardcode cyan, violet, purple, blue, or green PageHeader gradients to force color variety.',
       'Do not inject global CSS, create theme guards, redefine the app palette, or solve one extension by overriding the whole app shell.',
-      'For dynamic admin extensions, prefer the eApp CSS variables already present in the app: var(--surface-default), var(--surface-muted), var(--border-default), var(--text-primary), var(--text-secondary), and var(--text-tertiary).',
-      'Never use bare border/divide-y for panels or rows: pair them with border-[var(--border-default)] or divide-[var(--border-default)]. Avoid border-black, black, slate-only, gray-only, and dark-only palettes.',
-      'Status colors must remain readable in both themes; warning badges need high contrast text and a visible but not harsh border/background.',
+      'For panels/cards, prefer surface-card, surface-card-hover, surface-muted, or explicit token classes such as bg-[var(--card-bg)] border-[var(--card-border)] shadow-[var(--card-shadow)]. Use text-[var(--text-primary|secondary|tertiary)] for copy.',
+      'Never use Nuxt UI neutral semantic classes such as bg-default, bg-muted, border-default, divide-default, text-muted, text-dimmed, or hardcoded dark palettes such as dark:bg-zinc-950, bg-slate-*, text-gray-*, border-black, or black.',
+      'Never use bare border/divide-y for panels or rows: pair them with border-[var(--border-default)] or divide-[var(--border-default)].',
+      'Use radius tokens or mapped rounded utilities consistently: --radius-card for cards, --radius-panel for nested panels, --radius-control for buttons/inputs, --radius-subcontrol for compact inner controls, and --radius-pill for pills.',
+      'Status colors must remain readable in both themes. Use UBadge or badge tokens for non-primary statuses such as --badge-success-soft-*, --badge-warning-soft-*, --badge-danger-soft-*, --badge-info-soft-*, and --badge-neutral-soft-* instead of neon translucent colors.',
+      'Keep dark and light contrast comparable. Do not make dark mode more neon or lower-contrast than light mode; prefer muted soft backgrounds with clear text and visible borders.',
+    ],
+    components: [
+      'Use Nuxt UI/eApp components for normal controls: UButton, UInput, UTextarea, USelectMenu/USelect, USwitch, UCheckbox, UTabs, UBadge, UModal, and CommonDrawer when available.',
+      'Buttons should have stable geometry: hover may change color, border, or shadow but must not move the button or resize its content. Disabled buttons keep disabled cursor/visual state.',
+      'Inputs and textareas should not add hover movement or decorative hover states; focus, invalid, disabled, and loading states must be explicit.',
+      'Dynamic extensions resolve UModal to the app CommonModal. Do not pass ui.content: "surface-card" to UModal/CommonModal; modal content uses the app modal surface and caller ui.content should only append z-index, width, or max-width classes.',
+      'Use CommonDrawer for side-panel editing. Open drawers immediately on user action and render loading/error/content inside the drawer instead of waiting for fetch before opening.',
+      'Use UBadge or token-backed badge spans for status. Keep badges legible in both themes with tokenized background, text, and border.',
+    ],
+    loadingAndLists: [
+      'For first load of card/list pages, render calm skeleton cards with a slow pulse. For subsequent pagination/filter refreshes, keep the card shells mounted and skeletonize card content until the new list is ready.',
+      'Keep pagination inside the same transition/loading branch as the list. Do not show pagination before the list content has left loading.',
+      'Use bounded pagination for operational lists. Do not replace pagination with arbitrary fixed caps such as 30 or 50.',
+      'Empty states should use an app-matched card surface with compact icon tile, title, and description; do not use huge blank white panels or naked UEmpty chrome on page surfaces.',
     ],
     interaction: [
       'Every mutating button needs pending/disabled state, success/error feedback, and must close or update its modal when the operation completes.',
       'Do not refetch broad lists after selecting one row. Keep local selection state and fetch only the detail or mutation result needed.',
-      'Use bounded pagination for operational lists. Do not replace pagination with arbitrary fixed caps such as 30 or 50.',
       'Customer-facing toasts must describe the operation. Do not surface raw job ids, flow ids, or worker ids.',
     ],
     security: [
@@ -316,7 +339,7 @@ function getExtensionThemeContract() {
       'UI checks are only guidance; handlers/hooks must independently enforce owner/root-admin authorization.',
       'Use the most specific business route or MCP tool. Do not write directly to raw tables when a domain route exists.',
     ],
-    compactExample: '<template><section class="min-h-full w-full space-y-4"><div class="rounded-lg border border-[var(--border-default)] bg-[var(--surface-default)]"><div class="border-b border-[var(--border-default)] px-4 py-3"><h2 class="text-base font-semibold text-[var(--text-primary)]">Title</h2><p class="text-sm text-[var(--text-tertiary)]">Short operational context.</p></div><div class="divide-y divide-[var(--border-default)]"><button class="flex w-full items-center justify-between px-4 py-3 text-left hover:bg-[var(--surface-muted)]"><span class="text-sm font-medium text-[var(--text-primary)]">Row</span><span class="text-sm text-[var(--text-tertiary)]">Open</span></button></div></div></section></template>',
+    compactExample: '<template><section class="min-h-full w-full space-y-4"><div class="surface-card"><div class="border-b border-[var(--border-default)] px-4 py-3"><h2 class="text-base font-semibold text-[var(--text-primary)]">Title</h2><p class="text-sm text-[var(--text-tertiary)]">Short operational context.</p></div><div class="p-4"><article class="eapp-identity-surface rounded-[var(--radius-panel)] border p-4"><div class="flex items-center gap-3"><span class="eapp-identity-soft rounded-[var(--radius-control)] p-2"><span class="eapp-identity-text">◆</span></span><span class="text-sm font-medium text-[var(--text-primary)]">Identity block</span></div></article></div><div class="divide-y divide-[var(--border-default)]"><button class="flex w-full cursor-pointer items-center justify-between px-4 py-3 text-left transition-colors hover:bg-[var(--surface-muted)] disabled:cursor-not-allowed disabled:opacity-60"><span class="text-sm font-medium text-[var(--text-primary)]">Row</span><span class="eapp-identity-soft rounded-[var(--radius-pill)] px-2 py-0.5 text-xs font-semibold">Open</span></button></div><div class="h-1.5 overflow-hidden rounded-[var(--radius-pill)] bg-[var(--surface-muted)]"><div class="eapp-identity-solid h-full w-1/2"></div></div></div></section></template>',
   };
 }