@classic-homes/theme-mcp 0.1.26 → 0.1.28

package/dist/cli.js

@@ -14198,6 +14198,104 @@ var auth_catalog_default = {
               ]
             }
           ]
+        },
+        errors: {
+          description: "Custom error types for authentication operations",
+          functions: [
+            {
+              name: "RoleDeniedError",
+              signature: "class extends Error",
+              description: "Error thrown when a user authenticates but lacks required roles",
+              example: "import { authService, RoleDeniedError } from '@classic-homes/auth/core';\n\ntry {\n  const response = await authService.login(credentials, {\n    allowedRoles: ['admin', 'manager', 'agent'],\n  });\n} catch (error) {\n  if (error instanceof RoleDeniedError) {\n    // User authenticated but lacks required role\n    console.log('User roles:', error.user.roles);\n    console.log('Required roles:', error.requiredRoles);\n    goto('/auth/login?error=insufficient_permissions');\n  }\n}"
+            },
+            {
+              name: "isRoleDeniedError",
+              signature: "(error: unknown) => error is RoleDeniedError",
+              description: "Type guard to check if an error is a RoleDeniedError"
+            }
+          ],
+          types: [
+            {
+              name: "RoleDeniedError",
+              description: "Error with user and role information for handling access denial",
+              properties: [
+                { name: "name", type: "'RoleDeniedError'", required: true, description: "Error name for identification" },
+                { name: "user", type: "User", required: true, description: "The authenticated user (allows logging before redirect)" },
+                { name: "requiredRoles", type: "string[]", required: true, description: "The roles that were required (user has none of these)" },
+                { name: "redirectTo", type: "string", required: false, description: "Optional redirect path for convenience" },
+                { name: "message", type: "string", required: true, description: "Human-readable error message" }
+              ]
+            }
+          ]
+        },
+        "user-utils": {
+          description: "Helper functions for displaying user information in the UI",
+          functions: [
+            {
+              name: "getDisplayName",
+              signature: "(user: User | null | undefined) => string",
+              description: "Get a display-friendly name for a user. Priority: full name > first name > username > email > 'Unknown'",
+              example: `import { getDisplayName } from '@classic-homes/auth/core';
+
+const name = getDisplayName(user);
+// Returns: "John Doe", "John", "johndoe", or "john@example.com"`
+            },
+            {
+              name: "getUserInitials",
+              signature: "(user: User | null | undefined, maxLength?: number) => string",
+              description: "Get initials from a user's name for avatar fallbacks",
+              example: `import { getUserInitials } from '@classic-homes/auth/core';
+
+const initials = getUserInitials(user);
+// Returns: "JD" for "John Doe", "J" for "John", "?" for unknown`
+            },
+            {
+              name: "getAvatarFallback",
+              signature: "(user: User | null | undefined) => string",
+              description: "Get avatar fallback text for a user. Alias for getUserInitials for semantic clarity.",
+              example: "import { getAvatarFallback } from '@classic-homes/auth/core';\n\n<Avatar>\n  <AvatarFallback>{getAvatarFallback(user)}</AvatarFallback>\n</Avatar>"
+            },
+            {
+              name: "getUserEmail",
+              signature: "(user: User | null | undefined, masked?: boolean) => string",
+              description: "Get the user's primary email, optionally masked for privacy",
+              example: `import { getUserEmail } from '@classic-homes/auth/core';
+
+getUserEmail(user);        // "john@example.com"
+getUserEmail(user, true);  // "j***@example.com"`
+            },
+            {
+              name: "getGreeting",
+              signature: "(user: User | null | undefined, includeTime?: boolean) => string",
+              description: "Get a greeting for the user based on time of day",
+              example: `import { getGreeting } from '@classic-homes/auth/core';
+
+getGreeting(user);             // "Good morning, John"
+getGreeting(user, false);      // "Hello, John"`
+            },
+            {
+              name: "formatUserRoles",
+              signature: "(user: User | null | undefined, options?: FormatUserRolesOptions) => string",
+              description: "Format user roles for display with customizable formatting",
+              example: `import { formatUserRoles } from '@classic-homes/auth/core';
+
+formatUserRoles(user);                    // "Admin, Manager"
+formatUserRoles(user, { max: 1 });        // "Admin +1 more"
+formatUserRoles(user, { lowercase: true }); // "admin, manager"`
+            }
+          ],
+          types: [
+            {
+              name: "FormatUserRolesOptions",
+              description: "Options for formatUserRoles function",
+              properties: [
+                { name: "max", type: "number", required: false, description: "Maximum roles to show before '+N more'" },
+                { name: "separator", type: "string", required: false, description: "Separator between roles (default: ', ')" },
+                { name: "lowercase", type: "boolean", required: false, description: "Convert to lowercase (default: false)" },
+                { name: "capitalize", type: "boolean", required: false, description: "Capitalize first letter of each role (default: true)" }
+              ]
+            }
+          ]
         }
       },
       types: [
@@ -14509,9 +14607,9 @@ var auth_catalog_default = {
             },
             {
               name: "authActions",
-              signature: "{ setAuth, updateTokens, updateUser, logout, logoutWithSSO, hasPermission, hasRole, hasAnyRole, hasAllRoles, hasAnyPermission, hasAllPermissions, rehydrate }",
+              signature: "{ setAuth, updateTokens, updateUser, logout, logoutWithSSO, handleSessionExpired, hasPermission, hasRole, hasAnyRole, hasAllRoles, hasAnyPermission, hasAllPermissions, rehydrate, reset }",
               description: "Auth action functions that update the store and check permissions",
-              example: "import { authActions } from '@classic-homes/auth/svelte';\n\n// After successful login, set the auth state\nauthActions.setAuth(accessToken, refreshToken, user, sessionToken);\n\n// Update tokens after refresh\nauthActions.updateTokens(newAccessToken, newRefreshToken);\n\n// Update user data\nauthActions.updateUser(updatedUser);\n\n// Logout (clears local state)\nauthActions.logout();\n\n// Logout with SSO (calls API and clears state)\nconst { ssoLogoutUrl } = await authActions.logoutWithSSO();\nif (ssoLogoutUrl) window.location.href = ssoLogoutUrl;\n\n// Permission/role checks\nif (authActions.hasRole('admin')) { /* admin logic */ }\nif (authActions.hasPermission('users:write')) { /* write logic */ }"
+              example: "import { authActions } from '@classic-homes/auth/svelte';\n\n// After successful login, set the auth state\nauthActions.setAuth(accessToken, refreshToken, user, sessionToken);\n\n// Update tokens after refresh\nauthActions.updateTokens(newAccessToken, newRefreshToken);\n\n// Update user data\nauthActions.updateUser(updatedUser);\n\n// Logout (clears local state)\nauthActions.logout();\n\n// Logout with SSO (calls API and clears state)\nconst { ssoLogoutUrl } = await authActions.logoutWithSSO();\nif (ssoLogoutUrl) window.location.href = ssoLogoutUrl;\n\n// Handle session expiration (triggers onSessionExpired callback)\nauthActions.handleSessionExpired();\n\n// Permission/role checks\nif (authActions.hasRole('admin')) { /* admin logic */ }\nif (authActions.hasPermission('users:write')) { /* write logic */ }\n\n// Reset store for testing (clears state, storage, and subscribers)\nauthActions.reset();"
             }
           ]
         },
@@ -14576,6 +14674,141 @@ var auth_catalog_default = {
               ]
             }
           ]
+        },
+        client: {
+          description: "Simplified auth client factory for one-liner setup",
+          functions: [
+            {
+              name: "createAuthClient",
+              signature: "(options: CreateAuthClientOptions) => AuthClient",
+              description: "Create and initialize the auth client with stores and services bundled",
+              example: "import { createAuthClient } from '@classic-homes/auth/svelte';\nimport { PUBLIC_API_URL } from '$env/static/public';\n\n// In your lib/auth.ts\nexport const {\n  authStore,\n  authActions,\n  authService,\n  isAuthenticated,\n  currentUser,\n} = createAuthClient({\n  baseUrl: PUBLIC_API_URL,\n  storageKey: 'my_app_auth',\n  sso: { enabled: true, provider: 'authentik' },\n  onSessionExpired: (currentPath) => {\n    window.location.href = `/login?redirect=${encodeURIComponent(currentPath)}`;\n  },\n});\n\n// In Svelte component\nimport { isAuthenticated, currentUser } from '$lib/auth';\n\n{#if $isAuthenticated}\n  <p>Welcome, {$currentUser?.firstName}</p>\n{/if}"
+            },
+            {
+              name: "initAuth",
+              signature: "(config: AuthConfig) => void",
+              description: "Re-exported from core for cases where you need more control"
+            },
+            {
+              name: "isInitialized",
+              signature: "() => boolean",
+              description: "Re-exported from core to check if auth has been initialized"
+            }
+          ],
+          types: [
+            {
+              name: "CreateAuthClientOptions",
+              description: "Options for createAuthClient, extending AuthConfig",
+              properties: [
+                { name: "baseUrl", type: "string", required: true, description: "Base URL for the API" },
+                { name: "storageKey", type: "string", required: false, description: "Storage key prefix for auth data" },
+                { name: "autoRehydrate", type: "boolean", required: false, description: "Auto-rehydrate auth state from storage on creation (default: true)" },
+                { name: "sso", type: "SSOConfig", required: false, description: "SSO configuration" },
+                { name: "onSessionExpired", type: "(currentPath: string) => void", required: false, description: "Callback when session expires" },
+                { name: "onAuthError", type: "(error: Error) => void", required: false, description: "Callback for auth errors" },
+                { name: "onLogout", type: "() => void", required: false, description: "Callback when user logs out" }
+              ]
+            },
+            {
+              name: "AuthClient",
+              description: "Return type from createAuthClient with all auth utilities",
+              properties: [
+                { name: "authStore", type: "AuthStore", required: true, description: "The auth store (Svelte store contract)" },
+                { name: "authActions", type: "AuthActions", required: true, description: "Actions for modifying auth state" },
+                { name: "authService", type: "AuthService", required: true, description: "Service for API calls" },
+                { name: "isAuthenticated", type: "Readable<boolean>", required: true, description: "Derived store for isAuthenticated" },
+                { name: "currentUser", type: "Readable<User | null>", required: true, description: "Derived store for currentUser" }
+              ]
+            }
+          ]
+        },
+        hooks: {
+          description: "Server-side authentication middleware for SvelteKit hooks.server.ts",
+          functions: [
+            {
+              name: "createAuthHook",
+              signature: "(options?: AuthHookOptions) => Handle",
+              description: "Create a SvelteKit handle function for server-side authentication",
+              example: "// src/hooks.server.ts\nimport { createAuthHook } from '@classic-homes/auth/svelte';\nimport { sequence } from '@sveltejs/kit/hooks';\n\nconst authHook = createAuthHook({\n  loginPath: '/auth/login',\n  publicRoutes: [/^\\/auth\\//, /^\\/api\\/health/],\n  cookieName: 'my_app_auth',\n});\n\nexport const handle = sequence(authHook);"
+            },
+            {
+              name: "matchesRoute",
+              signature: "(pathname: string, patterns: RegExp[]) => boolean",
+              description: "Helper to check if a pathname matches any pattern in a list"
+            },
+            {
+              name: "routePatterns",
+              signature: "{ auth, api, apiAuth, public, admin, root, health, prefix, exact }",
+              description: "Pre-built route patterns for common use cases",
+              example: "import { createAuthHook, routePatterns } from '@classic-homes/auth/svelte';\n\nconst authHook = createAuthHook({\n  publicRoutes: [\n    routePatterns.auth,       // /auth/*\n    routePatterns.health,     // /health, /healthz, /ready, /live\n    routePatterns.exact('/about'),  // exact /about\n    routePatterns.prefix('/public'), // /public/*\n  ],\n  protectedRoutes: [\n    routePatterns.admin,      // /admin/*\n    routePatterns.api,        // /api/*\n  ],\n});"
+            }
+          ],
+          types: [
+            {
+              name: "AuthHookOptions",
+              description: "Configuration options for the auth hook",
+              properties: [
+                { name: "loginPath", type: "string", required: false, description: "Path to redirect unauthenticated users (default: '/login')" },
+                { name: "protectedRoutes", type: "RegExp[]", required: false, description: "Routes that require authentication. If set, only these routes need auth." },
+                { name: "publicRoutes", type: "RegExp[]", required: false, description: "Routes that don't require auth (default: [/^\\/auth\\//, /^\\/api\\/auth\\//])" },
+                { name: "cookieName", type: "string", required: false, description: "Cookie name for auth token (default: 'classic_auth')" },
+                { name: "headerName", type: "string", required: false, description: "Alternative header name to check for auth token" },
+                { name: "redirectParam", type: "string", required: false, description: "Query parameter for redirect URL (default: 'redirect')" },
+                { name: "isAuthenticated", type: "(event: RequestEvent) => boolean | Promise<boolean>", required: false, description: "Custom function to determine if request is authenticated" },
+                { name: "onUnauthenticated", type: "(event: RequestEvent) => Response | Promise<Response>", required: false, description: "Custom handler for unauthenticated requests" },
+                { name: "onAuthCheck", type: "(event: RequestEvent, isAuthenticated: boolean) => void", required: false, description: "Callback for auth check logging/analytics" }
+              ]
+            }
+          ]
+        },
+        utils: {
+          description: "Navigation filtering utilities based on user roles and permissions",
+          functions: [
+            {
+              name: "filterByAccess",
+              signature: "<T extends RoleRestrictedItem>(items: T[], user: User | null, options?: NavFilterOptions) => T[]",
+              description: "Filter navigation items based on user roles and permissions",
+              example: "import { filterByAccess } from '@classic-homes/auth/svelte';\n\nconst navItems = [\n  { id: 'dashboard', label: 'Dashboard' },\n  { id: 'users', label: 'Users', roles: ['admin', 'manager'] },\n  { id: 'settings', label: 'Settings', permissions: ['settings:read'] },\n];\n\nconst filtered = filterByAccess(navItems, user);\n// Returns items the user can see based on their roles/permissions"
+            },
+            {
+              name: "filterNavSections",
+              signature: "<TItem, TSection>(sections: TSection[], user: User | null, options?: NavFilterOptions) => TSection[]",
+              description: "Filter navigation sections with nested items, removing empty sections",
+              example: "import { filterNavSections } from '@classic-homes/auth/svelte';\n\nconst sections = [\n  {\n    title: 'Main',\n    items: [\n      { id: 'dashboard', label: 'Dashboard' },\n      { id: 'analytics', label: 'Analytics', roles: ['admin'] },\n    ],\n  },\n  {\n    title: 'Admin',\n    items: [\n      { id: 'users', label: 'Users', roles: ['admin'] },\n    ],\n  },\n];\n\nconst filtered = filterNavSections(sections, user);\n// Admin section removed entirely if user isn't admin"
+            },
+            {
+              name: "canAccess",
+              signature: "(item: RoleRestrictedItem, user: User | null, options?: NavFilterOptions) => boolean",
+              description: "Check if a user can access a specific item",
+              example: "import { canAccess } from '@classic-homes/auth/svelte';\n\nconst adminItem = { id: 'admin', roles: ['admin'] };\n\nif (canAccess(adminItem, user)) {\n  // Show admin link\n}"
+            },
+            {
+              name: "createNavFilter",
+              signature: "(defaultOptions?: NavFilterOptions) => FilterFunction",
+              description: "Create a pre-configured filter function with fixed options",
+              example: "import { createNavFilter } from '@classic-homes/auth/svelte';\n\n// In a config file\nexport const filterNav = createNavFilter({ requireAllRoles: false });\n\n// In components\nconst filtered = filterNav(items, user);"
+            }
+          ],
+          types: [
+            {
+              name: "RoleRestrictedItem",
+              description: "Interface for items that can be filtered by role/permission",
+              properties: [
+                { name: "id", type: "string", required: false, description: "Optional item identifier" },
+                { name: "roles", type: "string[]", required: false, description: "Roles that can see this item (any by default)" },
+                { name: "permissions", type: "string[]", required: false, description: "Permissions that can see this item (any by default)" }
+              ]
+            },
+            {
+              name: "NavFilterOptions",
+              description: "Options for navigation filtering behavior",
+              properties: [
+                { name: "requireAllRoles", type: "boolean", required: false, description: "Require ALL specified roles (default: false = any role)" },
+                { name: "requireAllPermissions", type: "boolean", required: false, description: "Require ALL specified permissions (default: false = any permission)" },
+                { name: "hideUnrestrictedForGuests", type: "boolean", required: false, description: "Hide unrestricted items for unauthenticated users (default: false)" }
+              ]
+            }
+          ]
         }
       }
     },
@@ -15279,7 +15512,7 @@ function registerAuthResources(server) {
     ]
   }));
   server.resource(
-    "Auth Module",
+    "Auth Core Module",
     new ResourceTemplate3("auth://core/{module}", { list: void 0 }),
     async (uri, params) => {
       const moduleName = params.module;
@@ -15293,7 +15526,40 @@ function registerAuthResources(server) {
               uri: uri.href,
               mimeType: "application/json",
               text: JSON.stringify({
-                error: `Module "${moduleName}" not found`,
+                error: `Module "${moduleName}" not found in core`,
+                availableModules
+              })
+            }
+          ]
+        };
+      }
+      return {
+        contents: [
+          {
+            uri: uri.href,
+            mimeType: "application/json",
+            text: JSON.stringify(module, null, 2)
+          }
+        ]
+      };
+    }
+  );
+  server.resource(
+    "Auth Svelte Module",
+    new ResourceTemplate3("auth://svelte/{module}", { list: void 0 }),
+    async (uri, params) => {
+      const moduleName = params.module;
+      const modules = catalog2.subpackages.svelte.modules;
+      const module = modules[moduleName];
+      if (!module) {
+        const availableModules = Object.keys(modules);
+        return {
+          contents: [
+            {
+              uri: uri.href,
+              mimeType: "application/json",
+              text: JSON.stringify({
+                error: `Module "${moduleName}" not found in svelte`,
                 availableModules
               })
             }
@@ -15323,6 +15589,10 @@ function registerAuthResources(server) {
               code: "import { initAuth } from '@classic-homes/auth/core';\n\ninitAuth({ baseUrl: 'https://api.example.com' });",
               description: "Initialize the auth system with your API base URL"
             },
+            createAuthClient: {
+              code: "import { createAuthClient } from '@classic-homes/auth/svelte';\n\nexport const { authStore, authActions, authService, isAuthenticated, currentUser } = createAuthClient({\n  baseUrl: 'https://api.example.com',\n  onSessionExpired: (path) => goto(`/login?redirect=${path}`),\n});",
+              description: "One-liner setup that bundles initialization, stores, and services"
+            },
             login: {
               code: "import { authApi, isMfaChallengeResponse } from '@classic-homes/auth/core';\n\nconst response = await authApi.login({ username: 'user@example.com', password: 'password' });\nif (isMfaChallengeResponse(response)) {\n  // Handle MFA\n}",
               description: "Login with username and password, handling MFA if required"
@@ -15332,9 +15602,25 @@ function registerAuthResources(server) {
               description: "Use reactive Svelte stores for auth state"
             },
             routeProtection: {
-              code: "import { requireAuth, requireRole } from '@classic-homes/auth/svelte';\n\n// In +page.ts or +layout.ts\nexport const load = requireAuth();\n// or\nexport const load = requireRole('admin');",
+              code: "import { requireAuth, requireRole } from '@classic-homes/auth/svelte';\nimport { redirect } from '@sveltejs/kit';\n\n// In +page.ts\nexport function load() {\n  const result = requireAuth();\n  if (!result.allowed) throw redirect(302, result.redirectTo ?? '/login');\n}",
               description: "Protect SvelteKit routes with auth guards"
             },
+            serverSideHooks: {
+              code: "// hooks.server.ts\nimport { createAuthHook, routePatterns } from '@classic-homes/auth/svelte';\nimport { sequence } from '@sveltejs/kit/hooks';\n\nconst authHook = createAuthHook({\n  publicRoutes: [routePatterns.auth, routePatterns.health],\n});\n\nexport const handle = sequence(authHook);",
+              description: "Server-side authentication middleware for SvelteKit"
+            },
+            navigationFiltering: {
+              code: "import { filterByAccess } from '@classic-homes/auth/svelte';\n\nconst navItems = [\n  { id: 'dashboard', label: 'Dashboard' },\n  { id: 'admin', label: 'Admin', roles: ['admin'] },\n];\n\nconst filtered = filterByAccess(navItems, user);",
+              description: "Filter navigation items based on user roles/permissions"
+            },
+            userDisplay: {
+              code: "import { getDisplayName, getUserInitials, getGreeting } from '@classic-homes/auth/core';\n\ngetDisplayName(user);     // 'John Doe'\ngetUserInitials(user);    // 'JD'\ngetGreeting(user);        // 'Good morning, John'",
+              description: "User display utilities for UI"
+            },
+            roleValidation: {
+              code: "import { authService, RoleDeniedError } from '@classic-homes/auth/core';\n\ntry {\n  await authService.login(credentials, { allowedRoles: ['admin', 'agent'] });\n} catch (e) {\n  if (e instanceof RoleDeniedError) {\n    // User authenticated but lacks role\n  }\n}",
+              description: "Validate roles during login and handle access denial"
+            },
             testing: {
               code: "import { setupTestAuth, mockUser, assertAuthenticated } from '@classic-homes/auth/testing';\n\nconst ctx = setupTestAuth();\n// Run tests\nctx.cleanup();",
               description: "Set up mocks for testing auth flows"