@enfyra/mcp-server 0.1.69 → 0.1.71

package/dist/lib/extension-theme-contract.js

@@ -0,0 +1,417 @@
+import { buildExtensionAccountPanelSnippet, buildExtensionDrawerSnippet, buildExtensionEmptyStateSnippet, buildExtensionFormEditorSnippet, buildExtensionMenuNotificationSnippet, buildExtensionModalSnippet, buildExtensionPageShellSnippet, buildExtensionPermissionGateSnippet, buildExtensionResourceGridSnippet, buildExtensionResourceListSnippet, buildExtensionTabsSnippet, buildExtensionUploadModalSnippet, buildExtensionWidgetSnippet, } from './extension-component-builders.js';
+import { buildExtensionApiUsageSnippet, buildExtensionConfirmSnippet, buildExtensionNotifySnippet, } from './extension-api-builders.js';
+import { reviewExtensionRuntimeContract, reviewExtensionUiContract, } from './extension-contract-review.js';
+const THEME_CLASS_INTENTS = {
+    neutral_surface: {
+        classes: 'eapp-surface-card eapp-radius-panel border eapp-divider',
+        use: 'Ordinary cards, panels, KPI containers, list containers, detail blocks, and status blocks that should stay neutral.',
+    },
+    muted_surface: {
+        classes: 'eapp-surface-muted eapp-radius-panel',
+        use: 'Recessed areas, tracks, secondary panels, or subdued containers.',
+    },
+    flat_surface: {
+        classes: 'eapp-surface-flat',
+        use: 'Flush content areas that should follow the app surface without card chrome.',
+    },
+    hover_row: {
+        classes: 'eapp-surface-hover eapp-divider',
+        use: 'Clickable rows inside lists or tables.',
+    },
+    primary_identity: {
+        classes: 'eapp-primary-surface eapp-radius-panel border',
+        use: 'A selected/current entity, active plan, active package, or the single larger block representing current identity.',
+    },
+    primary_soft_icon_tile: {
+        classes: 'eapp-primary-soft eapp-icon-tile',
+        childClasses: 'eapp-primary-text',
+        use: 'Compact runtime-primary icon tiles, selected chips, and small identity accents.',
+    },
+    primary_progress: {
+        trackClasses: 'eapp-surface-muted eapp-radius-pill',
+        fillClasses: 'eapp-primary-solid',
+        use: 'Progress or meter fill controlled by the runtime primary color.',
+    },
+    status_success: {
+        classes: 'eapp-status-success-soft eapp-status-success-text eapp-status-success-border',
+        nuxtUi: { color: 'success', variant: 'soft' },
+        use: 'Small success/healthy badges, chips, or icons only.',
+    },
+    status_warning: {
+        classes: 'eapp-status-warning-soft eapp-status-warning-text eapp-status-warning-border',
+        nuxtUi: { color: 'warning', variant: 'soft' },
+        use: 'Small warning/attention badges, chips, or icons only.',
+    },
+    status_danger: {
+        classes: 'eapp-status-danger-soft eapp-status-danger-text eapp-status-danger-border',
+        nuxtUi: { color: 'error', variant: 'soft' },
+        use: 'Small danger/error/destructive badges, chips, or icons only.',
+    },
+    status_info: {
+        classes: 'eapp-status-info-soft eapp-status-info-text eapp-status-info-border',
+        nuxtUi: { color: 'info', variant: 'soft' },
+        use: 'Small informational badges, chips, or icons only.',
+    },
+    primary_action: {
+        nuxtUi: { color: 'primary', variant: 'solid' },
+        use: 'The single main action for the current scope.',
+    },
+    secondary_action: {
+        nuxtUi: { color: 'neutral', variant: 'outline' },
+        use: 'Visible secondary actions, refresh, filters, cancel, and navigation alternatives.',
+    },
+    ghost_navigation_action: {
+        nuxtUi: { color: 'neutral', variant: 'ghost' },
+        use: 'Back/navigation/icon actions that should not compete with the primary action.',
+    },
+    danger_action: {
+        nuxtUi: { color: 'error', variant: 'solid' },
+        use: 'Final destructive actions such as Delete or Remove.',
+    },
+    divider: {
+        classes: 'eapp-divider',
+        listClasses: 'eapp-divide-y',
+        use: 'Borders and row separators in extension UI.',
+    },
+    text: {
+        primary: 'eapp-text-primary',
+        secondary: 'eapp-text-secondary',
+        tertiary: 'eapp-text-tertiary',
+        quaternary: 'eapp-text-quaternary',
+        use: 'Copy hierarchy in extension UI.',
+    },
+};
+function buildExtensionThemeClasses(input = {}) {
+    const intent = String(input.intent || '').trim();
+    if (!intent || !(intent in THEME_CLASS_INTENTS)) {
+        return {
+            action: 'extension_theme_classes_listed',
+            validIntents: Object.keys(THEME_CLASS_INTENTS),
+            note: 'Call again with one intent to get the exact classes/props for that theme contract.',
+        };
+    }
+    const contract = THEME_CLASS_INTENTS[intent];
+    return {
+        action: 'extension_theme_classes_built',
+        intent,
+        contract,
+        hardRules: [
+            'Do not use raw CSS variable utilities such as text-[var(...)], bg-[var(...)], or border-[var(...)] in extension templates.',
+            'Do not use hardcoded Tailwind palettes such as bg-violet-*, text-cyan-*, bg-green-*, dark:bg-zinc-*, or hex/rgb/hsl colors.',
+            'Use status classes only for compact badges/icons/short text; keep large panels neutral.',
+        ],
+    };
+}
+function collectExtensionThemeIssues(code) {
+    const source = String(code || '');
+    const issues = [];
+    const push = (severity, rule, message, suggestion) => issues.push({ severity, rule, message, suggestion });
+    const concretePalettes = [
+        'slate', 'gray', 'zinc', 'neutral', 'stone',
+        'red', 'orange', 'amber', 'yellow', 'lime', 'green', 'emerald', 'teal', 'cyan', 'sky', 'blue', 'indigo',
+        'violet', 'purple', 'fuchsia', 'pink', 'rose',
+    ].join('|');
+    const paletteClassPattern = new RegExp(`(?:^|[\\s"'])(?:dark:)?(?:bg|text|border|ring|divide|from|via|to)-(${concretePalettes})-(?:\\d{2,3}|950)(?:\\/\\d+)?`, 'i');
+    const rawCssVarPattern = /\b(?:bg|text|border|ring|divide|from|via|to)-\[\s*var\(--/i;
+    const neutralSemanticClassPattern = /\b(?:bg-default|bg-muted|border-default|divide-default|text-muted|text-dimmed)\b/;
+    const concreteNuxtUiColors = [
+        'slate', 'gray', 'zinc', 'stone',
+        'red', 'orange', 'amber', 'yellow', 'lime', 'green', 'emerald', 'teal', 'cyan', 'sky', 'blue', 'indigo',
+        'violet', 'purple', 'fuchsia', 'pink', 'rose',
+    ].join('|');
+    const concreteNuxtColorPattern = new RegExp(`\\bcolor\\s*=\\s*["'](${concreteNuxtUiColors})["']`, 'i');
+    if (rawCssVarPattern.test(source)) {
+        push('error', 'raw-css-var-utility', 'Raw CSS variable utility classes are not allowed in generated extension templates.', 'Use eapp-* class tokens or Nuxt UI semantic color props by intent.');
+    }
+    if (paletteClassPattern.test(source)) {
+        push('error', 'hardcoded-tailwind-palette', 'Hardcoded Tailwind palette classes are not allowed in themeable extension UI.', 'Use eapp-surface-*, eapp-primary-*, eapp-status-*, or Nuxt UI semantic colors.');
+    }
+    if (neutralSemanticClassPattern.test(source)) {
+        push('error', 'nuxt-neutral-class', 'Nuxt UI neutral shortcut classes are not part of the extension theme contract.', 'Use eapp-surface-* and eapp-text-* classes instead.');
+    }
+    if (concreteNuxtColorPattern.test(source)) {
+        push('error', 'concrete-nuxt-color', 'Concrete Nuxt UI palette colors are not allowed in generated extension UI.', 'Use color="primary|neutral|success|warning|error|info" by semantic intent.');
+    }
+    if (/#(?:[0-9a-f]{3,4}|[0-9a-f]{6}|[0-9a-f]{8})\b/i.test(source) || /\b(?:rgba?|hsla?|oklch|lab|lch)\s*\(/i.test(source)) {
+        push('error', 'hardcoded-color-value', 'Hardcoded color values are not allowed in extension UI.', 'Use the Enfyra theme class contract instead of hex/rgb/hsl/oklch/lab/lch values.');
+    }
+    if (/\bstyle\s*=\s*["'][^"']*(?:color|background(?:-color)?|border-color)\s*:/i.test(source)) {
+        push('error', 'inline-color-style', 'Inline color styles bypass the app theme contract.', 'Use eapp-* classes or Nuxt UI semantic props instead of inline color/background/border-color.');
+    }
+    if (/\bgradient\s*:\s*['"](?!none['"])[^'"]+['"]/.test(source) || /\bgradient\s*=\s*['"](?!none['"])[^'"]+['"]/.test(source)) {
+        push('error', 'page-header-gradient', 'Generated operational extension pages must use PageHeader gradient "none" unless the user explicitly requests decoration.', 'Set gradient: "none" in usePageHeaderRegistry or omit decorative gradients.');
+    }
+    if (/<(?:article|section|div)\b[^>]*class=["'][^"']*(?:eapp-status-(?:success|warning|danger|info)-soft|bg-(?:success|warning|error|info)(?:\b|\/))/i.test(source)) {
+        push('warning', 'large-status-surface', 'Status color appears on a large container.', 'Keep large panels neutral and put status color on a compact UBadge/icon/short text inside.');
+    }
+    const primaryActionCount = (source.match(/\bcolor\s*=\s*["']primary["']/g) || []).length;
+    if (primaryActionCount > 2) {
+        push('warning', 'primary-overuse', 'Many primary-colored controls were found.', 'Use primary only for the main action or identity accent; use neutral variants for secondary actions.');
+    }
+    const primarySurfaceCount = (source.match(/\beapp-primary-surface\b/g) || []).length;
+    if (primarySurfaceCount > 3) {
+        push('warning', 'primary-surface-overuse', 'eapp-primary-surface appears many times.', 'Use eapp-primary-surface only for selected/current identity blocks, not every card in a list/grid.');
+    }
+    if (/<(?:article|section|div)\b[^>]*class=["'][^"']*\bborder\b(?![^"']*\beapp-divider\b)/i.test(source)) {
+        push('warning', 'bare-border-token', 'A bordered panel is missing eapp-divider.', 'Pair intentional borders with eapp-divider so borders follow the app theme contract.');
+    }
+    return issues;
+}
+export function reviewExtensionThemeContract(code) {
+    const issues = collectExtensionThemeIssues(code);
+    return {
+        action: 'extension_theme_contract_reviewed',
+        valid: issues.every((issue) => issue.severity !== 'error'),
+        issueCount: issues.length,
+        issues,
+        nextSteps: issues.length
+            ? ['Use build_extension_ui kind=theme_classes to choose classes/props by intent, then patch/update the extension.']
+            : ['Snippet matches the checked theme contract rules. Still validate the final SFC before saving.'],
+    };
+}
+export function buildExtensionUiSnippet(kind, input = {}) {
+    let result;
+    switch (kind) {
+        case 'drawer':
+            result = buildExtensionDrawerSnippet(input);
+            break;
+        case 'modal':
+            result = buildExtensionModalSnippet(input);
+            break;
+        case 'page_shell':
+            result = buildExtensionPageShellSnippet(input);
+            break;
+        case 'permission_gate':
+            result = buildExtensionPermissionGateSnippet(input);
+            break;
+        case 'empty_state':
+            result = buildExtensionEmptyStateSnippet(input);
+            break;
+        case 'resource_list':
+            result = buildExtensionResourceListSnippet(input);
+            break;
+        case 'resource_grid':
+            result = buildExtensionResourceGridSnippet(input);
+            break;
+        case 'form_editor':
+            result = buildExtensionFormEditorSnippet(input);
+            break;
+        case 'widget':
+            result = buildExtensionWidgetSnippet(input);
+            break;
+        case 'menu_notification':
+            result = buildExtensionMenuNotificationSnippet(input);
+            break;
+        case 'account_panel_item':
+            result = buildExtensionAccountPanelSnippet(input);
+            break;
+        case 'tabs':
+            result = buildExtensionTabsSnippet(input);
+            break;
+        case 'upload_modal':
+            result = buildExtensionUploadModalSnippet(input);
+            break;
+        case 'api_usage':
+            result = buildExtensionApiUsageSnippet(input);
+            break;
+        case 'notify':
+            result = buildExtensionNotifySnippet(input);
+            break;
+        case 'confirm':
+            result = buildExtensionConfirmSnippet(input);
+            break;
+        case 'runtime_review':
+            if (!input?.code) {
+                throw new Error('build_extension_ui kind=runtime_review requires input.code.');
+            }
+            result = reviewExtensionRuntimeContract(input.code);
+            break;
+        case 'theme_classes':
+            result = buildExtensionThemeClasses(input);
+            break;
+        case 'theme_review':
+            if (!input?.code) {
+                throw new Error('build_extension_ui kind=theme_review requires input.code.');
+            }
+            result = reviewExtensionThemeContract(input.code);
+            break;
+        case 'review':
+            if (!input?.code) {
+                throw new Error('build_extension_ui kind=review requires input.code.');
+            }
+            const uiReview = reviewExtensionUiContract(input.code, { pattern: input.pattern });
+            const themeReview = reviewExtensionThemeContract(input.code);
+            const runtimeReview = reviewExtensionRuntimeContract(input.code);
+            result = {
+                action: 'extension_ui_theme_runtime_contract_reviewed',
+                valid: uiReview.valid && themeReview.valid && runtimeReview.valid,
+                issueCount: uiReview.issueCount + themeReview.issueCount + runtimeReview.issueCount,
+                ui: uiReview,
+                theme: themeReview,
+                runtime: runtimeReview,
+            };
+            break;
+        default:
+            throw new Error(`Unsupported extension UI builder kind: ${kind}`);
+    }
+    return {
+        gateway: 'build_extension_ui',
+        kind,
+        ...result,
+    };
+}
+export function getExtensionThemeContract() {
+    return {
+        action: 'extension_theme_contract',
+        useBefore: [
+            'Call this before writing or reviewing Enfyra admin page, widget, or global extension UI.',
+            'Then call validate_extension_code or an ensure_*_extension tool before saving.',
+        ],
+        layout: [
+            '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.',
+            'Register dynamic extension header actions inside onMounted after setup refs and handlers exist; build_extension_ui kind=page_shell generates this lifecycle shape.',
+            'Use build_extension_ui kind=menu_notification for sidebar menu notification registration snippets.',
+            'For shell menu notifications, first decide the signal source. Use a count only when the source already owns an exact count, such as a notification summary endpoint or bounded unread-notification query. Use a dot when a realtime event only proves that something new exists. Do not poll a domain list such as messages, tickets, orders, or jobs solely to decorate the menu; the destination page owns domain fetching.',
+            'Use build_extension_ui kind=account_panel_item for account panel row registration snippets.',
+            '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: [
+            'Do not choose theme classes from memory. Decide the UI intent, then call build_extension_ui kind=theme_classes with that intent to receive the exact class/prop contract.',
+            'Call build_extension_ui kind=theme_review or kind=review before saving extension UI; validate_extension_code and extension write tools also reject hard theme violations.',
+            'Never fix one extension by injecting global CSS, redefining the app palette, or adding theme guards.',
+            'Use get_theme_class_reference only when debugging theme internals or when the user explicitly asks for the full theme/class map.',
+        ],
+        themeIntents: [
+            'neutral_surface',
+            'muted_surface',
+            'flat_surface',
+            'hover_row',
+            'primary_identity',
+            'primary_soft_icon_tile',
+            'primary_progress',
+            'status_success',
+            'status_warning',
+            'status_danger',
+            'status_info',
+            'primary_action',
+            'secondary_action',
+            'ghost_navigation_action',
+            'danger_action',
+            'divider',
+            'text',
+        ],
+        components: [
+            'Use Nuxt UI/eApp components for normal controls: UButton, UInput, UTextarea, USelectMenu/USelect, USwitch, UCheckbox, UTabs, UBadge, UModal, and CommonDrawer when available.',
+            'Use auto-injected components directly in the template with PascalCase names. Do not call resolveComponent() to manually resolve Nuxt UI/eApp components inside extension SFCs; it can compile but render unresolved lowercase DOM tags such as <ubutton>.',
+            '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.',
+            'For drawers, modals, page shell headers/actions, permission gates, empty states, resource lists, resource grids, form editors, widgets, menu/account panel registries, tabs, upload modals, api_usage, notify, and runtime/theming reviews, call build_extension_ui with the matching kind after extension acknowledgement before patching raw Vue.',
+            'Use build_extension_ui kind=theme_classes for theme classes by intent, and kind=runtime_review, theme_review, or review before saving generated snippets that include composables, theme classes, high-contract UI, or native buttons.',
+            'Use build_extension_ui kind=resource_grid for workboards, dashboards, catalogs, and responsive card collections instead of placing UCard children directly into a full-width list frame.',
+            'Use the EmptyState runtime alias returned by build_extension_ui kind=empty_state; CommonEmptyState is not registered as a dynamic extension tag.',
+            'Extension validation rejects UInput, UTextarea, USelect, USelectMenu, UInputMenu, UInputNumber, UInputTags, UInputTime, and UInputDate without class="w-full" unless marked data-compact or data-inline.',
+            'Use UBadge or token-backed badge spans for status. Keep badges legible in both themes with tokenized background, text, and border.',
+        ],
+        appComposables: [
+            'Call useApi() as a top-level setup composable. It returns data/error/pending/status refs plus execute/refresh; call or await execute()/refresh() from onMounted, watchers, or user actions when the request should run.',
+            'Do not write useNotify shapes from memory. Use build_extension_ui kind=notify for known-good notification snippets. Use build_extension_ui kind=api_usage only when a generated fetch/mutation scaffold is useful.',
+            'Use build_extension_ui kind=runtime_review or kind=review before saving extension code that includes useApi, useNotify, getPackages, or package loading.',
+            'validate_extension_code and extension write tools reject static imports, useToast/useNotify.add misuse, and JSON.stringify useApi options.',
+        ],
+        shellComponentContracts: {
+            CommonDrawer: [
+                'Use build_extension_ui kind=drawer for generated drawer/editing snippets.',
+                'The builder owns slots, managed footer actions, full-width fields, native button types, and loading/error/body structure. CommonDrawer disables drag dismissal globally; do not add handle-only, drag handlers, or swipe-to-close behavior.',
+            ],
+            CommonModal: [
+                'Use build_extension_ui kind=modal for generated modal/confirmation snippets.',
+                'The builder owns UModal/CommonModal aliasing, slots, managed footer actions, full-width fields, native button types, and modal surface constraints.',
+            ],
+            PermissionGate: [
+                'Use build_extension_ui kind=permission_gate for generated permission wrapper snippets.',
+                'UI gates are operator UX only; backend route permissions and handler/hook owner checks remain authoritative.',
+            ],
+            Widget: [
+                'Use build_extension_ui kind=widget for generated widget include snippets.',
+                'The builder owns numeric id usage, reactive prop/event wiring, and page/widget ownership warnings.',
+            ],
+            actionButtons: [
+                'Use build_extension_ui kind=review for generated snippets with native buttons or theme classes.',
+                'Validation/review catches missing type="button" and high-contract component mistakes before saving.',
+            ],
+        },
+        loadingAndLists: [
+            'For first load of card/list pages, render calm skeleton cards with a slow pulse. Use USkeleton or shared loading components so the app-owned skeleton theme controls contrast and accent matching. 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.',
+            'Customer-facing toasts must describe the operation. Do not surface raw job ids, flow ids, or worker ids.',
+        ],
+        security: [
+            'Decide route permission, owner scope, and field exposure before writing UI or backend logic.',
+            '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.',
+        ],
+        shellNotificationContract: {
+            menu: 'useMenuNotificationRegistry().register({ id, target: { id?, path?, route? }, value?, color?, title?, order? }). value renders a count/chip; omitting value renders a dot. Parent menus sum numeric child values.',
+            accountPanel: 'useAccountPanelRegistry().register({ id, label, description, icon, count?, badge?, badgeColor?, expanded?, onToggle?, contentComponent? }). count is preferred over badge and the account trigger sums numeric visible item counts, capped at 99+.',
+            lifecycle: 'Register from global extensions for app-wide notification state; stable ids replace previous registrations and component-owned registrations are removed on unmount.',
+            reasoning: 'Counts and dots are different promises. A count says the shell knows an exact or bounded number from an appropriate notification/summary source. A dot says the shell only knows that new attention exists. Avoid fetching the destination domain list just to make a menu badge more precise.',
+        },
+    };
+}
+export function getThemeClassReference() {
+    return {
+        action: 'theme_class_reference',
+        authority: 'Authoritative Enfyra theme & color contract. Source of truth: documents/app/theme-color-contract.md. App owns color via theme.css + main.css + app.config.ts only; pages/extensions consume classes and Nuxt UI props.',
+        baseLayers: {
+            material: '--md-* (runtime primary picker, HCT/Material You). Drives identity/brand. Never read directly in templates.',
+            status: '--st-success/--st-warning/--st-error/--st-info. Fixed semantic palette. Never read directly in templates.',
+        },
+        nuxtUiColors: {
+            primary: 'runtime --md-primary (main brand action/identity). NEVER substitute a concrete palette.',
+            secondary: 'runtime --md-tertiary (intentional secondary accent only).',
+            success: '--st-success (healthy/success).',
+            warning: '--st-warning (pending/attention).',
+            error: 'single --danger-* lane from Material error roles (destructive/error). Ghost danger text uses --danger-on-surface; danger fills use --danger-surface.',
+            info: '--st-info (informational).',
+            neutral: 'neutral surfaces (secondary chrome, non-actions).',
+        },
+        classes: [
+            { group: 'Surfaces (large ordinary - keep neutral)', classes: 'eapp-surface-card, eapp-surface-muted, eapp-surface-flat, eapp-surface-hover' },
+            { group: 'Text', classes: 'eapp-text-primary, eapp-text-secondary, eapp-text-tertiary, eapp-text-quaternary' },
+            { group: 'Runtime primary identity', classes: 'eapp-primary-solid, eapp-primary-text, eapp-primary-soft(+hover), eapp-primary-subtle, eapp-primary-surface(+hover), eapp-primary-border, eapp-primary-ring' },
+            { group: 'Status (badges/small icons/short text only)', classes: 'eapp-status-{success|warning|danger|info|neutral}-{soft|text|border}' },
+            { group: 'Radius', classes: 'eapp-radius-card, eapp-radius-panel, eapp-radius-control, eapp-radius-subcontrol, eapp-radius-pill' },
+            { group: 'Icon tile geometry', classes: 'eapp-icon-tile, eapp-icon-tile-sm, eapp-icon-tile-lg' },
+            { group: 'Dividers', classes: 'eapp-divider, eapp-divide-y' },
+            { group: 'Modal', classes: 'eapp-modal-surface (never surface-card as modal ui.content)' },
+        ],
+        forbidden: [
+            'Raw CSS variables in templates: text-[var(--*)], bg-[var(--*)], border-[var(--*)].',
+            'Tailwind palette accents: from-cyan-*, text-violet-*, bg-green-*, bg-emerald-*, text-gray-*, bg-slate-*, dark:bg-zinc-950.',
+            'Concrete palette substitution (color="violet"/"cyan"/..., from-cyan-*, text-violet-*, bg-green-*, bg-emerald-*, dark:bg-zinc-950).',
+            'Hardcoded hex colors or inline style="color:#..." for theme-driven surfaces.',
+            'Reading --md-* / --st-* / --badge-* base variables directly from extension templates.',
+        ],
+        allowedShortUtilities: [
+            'Tailwind v4 short utilities ARE canonical and preferred: bg-primary, text-primary, border-primary, ring-primary, bg-success, text-error, bg-warning, text-info, bg-secondary.',
+            'Opacity modifiers work natively via v4 color-mix: bg-primary/10, ring-primary/20, text-primary/70, bg-success/15.',
+            'Use eapp-* classes only for intent surfaces with no Tailwind equivalent (eapp-primary-surface/solid/soft/subtle, eapp-surface-card/muted/flat/hover, eapp-divider/divide-y, eapp-radius-*, eapp-modal-surface).',
+        ],
+        chooseByIntent: [
+            'Normal accent / active tab / progress / primary CTA -> primary (eapp-primary-* or color="primary").',
+            'True semantic state -> status (eapp-status-* or color="success|warning|error|info").',
+            'Large ordinary surface -> eapp-surface-*; put a small status badge inside.',
+            'Whole block is active identity -> eapp-primary-surface (+hover), subtle only.',
+        ],
+    };
+}
+//# sourceMappingURL=extension-theme-contract.js.map

package/dist/lib/extension-theme-contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extension-theme-contract.js","sourceRoot":"","sources":["../../src/lib/extension-theme-contract.ts"],"names":[],"mappings":"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"}

package/dist/lib/identity-tools.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Enfyra MCP — stdio server (loaded by index.ts / dist/index.js).
+ */
+export declare function registerIdentityTools(server: any, ENFYRA_API_URL: any): void;

package/dist/lib/identity-tools.js

@@ -0,0 +1,46 @@
+/**
+ * Enfyra MCP — stdio server (loaded by index.ts / dist/index.js).
+ */
+import { z } from 'zod';
+// Import modules
+import { exchangeApiToken, getTokenExpiry, initAuth } from './auth.js';
+import { fetchAPI } from './fetch.js';
+import { jsonContent } from './response-format.js';
+import { DEFAULT_ME_PERMISSION_FIELDS, ENFYRA_API_TOKEN, firstDataRecord, summarizePermissionProfile, } from './enfyra-tool-logic.js';
+export function registerIdentityTools(server, ENFYRA_API_URL) {
+    // ============================================================================
+    // AUTH & USER TOOLS
+    // ============================================================================
+    server.tool('get_current_user', 'Get current authenticated user info', {}, async () => {
+        const result = await fetchAPI(ENFYRA_API_URL, '/me');
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    });
+    server.tool('get_permission_profile', [
+        'Inspect the current token permission profile using the same route-permission model as Enfyra admin UI usePermissions().',
+        'Use this before debugging 403s or before relying on admin helper tools with a non-root API token.',
+        'Reports which MCP tool groups need route permissions such as /admin/script/validate, /admin/test/run, /admin/flow/trigger/:id, and reload endpoints.',
+    ].join(' '), {}, async () => {
+        const fields = DEFAULT_ME_PERMISSION_FIELDS.join(',');
+        const result = await fetchAPI(ENFYRA_API_URL, `/me?fields=${encodeURIComponent(fields)}`);
+        const user = firstDataRecord(result);
+        return jsonContent(summarizePermissionProfile(user));
+    });
+    server.tool('get_all_roles', 'Get all role definitions', {}, async () => {
+        const result = await fetchAPI(ENFYRA_API_URL, '/enfyra_role?limit=100');
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    });
+    server.tool('login', 'Force authentication to Enfyra and get a new access token', {
+        apiToken: z.string().optional().describe('API token for MCP and automation'),
+    }, async ({ apiToken }) => {
+        const token = apiToken || ENFYRA_API_TOKEN;
+        if (token) {
+            initAuth(ENFYRA_API_URL, token);
+            await exchangeApiToken(ENFYRA_API_URL, token);
+            const expiry = getTokenExpiry();
+            const expiryLabel = expiry === Infinity ? 'no expiration' : new Date(expiry).toISOString();
+            return { content: [{ type: 'text', text: `Authenticated with API token.\nToken expires: ${expiryLabel}` }] };
+        }
+        throw new Error('ENFYRA_API_TOKEN required');
+    });
+}
+//# sourceMappingURL=identity-tools.js.map

package/dist/lib/identity-tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity-tools.js","sourceRoot":"","sources":["../../src/lib/identity-tools.ts"],"names":[],"mappings":"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"}

package/dist/lib/log-tools.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Enfyra MCP — stdio server (loaded by index.ts / dist/index.js).
+ */
+export declare function registerLogTools(server: any, ENFYRA_API_URL: any): void;

package/dist/lib/log-tools.js

@@ -0,0 +1,65 @@
+/**
+ * Enfyra MCP — stdio server (loaded by index.ts / dist/index.js).
+ */
+import { z } from 'zod';
+import { fetchAPI } from './fetch.js';
+export function registerLogTools(server, ENFYRA_API_URL) {
+    // ============================================================================
+    // LOGS TOOLS
+    // ============================================================================
+    server.tool('get_log_files', 'List available log files and stats', {}, async () => {
+        const result = await fetchAPI(ENFYRA_API_URL, '/logs');
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    });
+    server.tool('get_log_content', 'Get content of a specific log file', {
+        filename: z.string().describe('Log file name'),
+        page: z.number().optional().default(1).describe('Page number'),
+        pageSize: z.number().optional().default(100).describe('Lines per page'),
+        filter: z.string().optional().describe('Text filter'),
+        level: z.string().optional().describe('Log level filter (INFO, WARN, ERROR)'),
+    }, async ({ filename, page, pageSize, filter, level }) => {
+        const queryParams = new URLSearchParams();
+        if (page)
+            queryParams.set('page', String(page));
+        if (pageSize)
+            queryParams.set('pageSize', String(pageSize));
+        if (filter)
+            queryParams.set('filter', filter);
+        if (level)
+            queryParams.set('level', level);
+        const result = await fetchAPI(ENFYRA_API_URL, `/logs/${filename}${queryParams.toString() ? `?${queryParams.toString()}` : ''}`);
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    });
+    server.tool('tail_log', 'Get last N lines from a log file', {
+        filename: z.string().describe('Log file name'),
+        lines: z.number().optional().default(50).describe('Number of lines to retrieve'),
+    }, async ({ filename, lines }) => {
+        const result = await fetchAPI(ENFYRA_API_URL, `/logs/${filename}/tail?lines=${lines}`);
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    });
+    server.tool('search_logs', 'Search for ERROR or WARN logs across recent log files', {
+        level: z.enum(['ERROR', 'WARN', 'INFO']).optional().default('ERROR').describe('Log level'),
+        keyword: z.string().optional().describe('Keyword to filter logs'),
+        limit: z.number().optional().default(50).describe('Max results per level'),
+    }, async ({ level, keyword, limit }) => {
+        const logFilesResult = await fetchAPI(ENFYRA_API_URL, '/logs');
+        const logFiles = logFilesResult.files || [];
+        const recentFiles = logFiles.filter((file) => {
+            const name = file?.name || '';
+            return /^app[.-]/.test(name) || /^error[.-]/.test(name);
+        });
+        const results = [];
+        for (const file of recentFiles.slice(0, 3)) {
+            try {
+                const contentResult = await fetchAPI(ENFYRA_API_URL, `/logs/${file.name}?level=${level}&pageSize=${limit}`);
+                const lines = contentResult.lines || contentResult.data || [];
+                const filteredLines = keyword ? lines.filter(l => JSON.stringify(l).toLowerCase().includes(keyword.toLowerCase())) : lines;
+                if (filteredLines.length > 0)
+                    results.push({ file: file.name, level, logs: filteredLines });
+            }
+            catch (e) { /* skip */ }
+        }
+        return { content: [{ type: 'text', text: `Found ${results.length} files:\n${JSON.stringify(results, null, 2)}` }] };
+    });
+}
+//# sourceMappingURL=log-tools.js.map

package/dist/lib/log-tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"log-tools.js","sourceRoot":"","sources":["../../src/lib/log-tools.ts"],"names":[],"mappings":"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"}

package/dist/lib/mcp-example-connect.d.ts

@@ -0,0 +1,9 @@
+export declare const connectExamples: {
+    title: string;
+    useWhen: string;
+    examples: {
+        name: string;
+        code: string;
+        notes: string[];
+    }[];
+};