@htlkg/astro 0.0.1

package/src/htlkg/config.ts

@@ -0,0 +1,242 @@
+/**
+ * Configuration types for the htlkg Astro integration
+ */
+
+import type { AuthUser } from '@htlkg/core/types';
+
+// Re-export AuthUser for convenience
+export type { AuthUser };
+
+/**
+ * Route pattern that can be either a RegExp or a string.
+ * - String patterns match exact paths or paths that start with the pattern
+ * - RegExp patterns allow for more complex matching logic
+ *
+ * @example
+ * // String pattern - matches /login and /login/*
+ * '/login'
+ *
+ * @example
+ * // RegExp pattern - matches /api/v1/* and /api/v2/*
+ * /^\/api\/v[12]\//
+ */
+export type RoutePattern = RegExp | string;
+
+/**
+ * Configuration for brand-specific routes that require brand ID extraction.
+ * The pattern should include a capture group for the brand ID.
+ *
+ * @example
+ * {
+ *   pattern: /^\/brands\/(\d+)/,
+ *   brandIdParam: 1  // First capture group
+ * }
+ */
+export interface BrandRouteConfig {
+	/**
+	 * Regular expression pattern with a capture group for the brand ID
+	 */
+	pattern: RegExp;
+
+	/**
+	 * Index of the capture group containing the brand ID (1-based)
+	 */
+	brandIdParam: number;
+}
+
+/**
+ * Configuration for the default login page injected by the integration.
+ */
+export interface LoginPageConfig {
+	/**
+	 * URL path where the login page should be accessible.
+	 * @default '/login'
+	 */
+	path?: string;
+
+	/**
+	 * Logo URL to display on the login page.
+	 * @default undefined
+	 */
+	logo?: string;
+
+	/**
+	 * Title text to display on the login page.
+	 * @default 'Sign In'
+	 */
+	title?: string;
+
+	/**
+	 * URL to redirect to after successful login.
+	 * @default '/admin'
+	 */
+	redirectUrl?: string;
+}
+
+/**
+ * Configuration for route guards that protect routes based on authentication
+ * status and user permissions.
+ *
+ * @example
+ * {
+ *   publicRoutes: ['/login', '/register', /^\/public\//],
+ *   authenticatedRoutes: ['/dashboard', /^\/profile/],
+ *   adminRoutes: ['/admin', /^\/admin\//],
+ *   brandRoutes: [
+ *     { pattern: /^\/brands\/(\d+)/, brandIdParam: 1 }
+ *   ],
+ *   loginUrl: '/login'
+ * }
+ */
+export interface RouteGuardConfig {
+	/**
+	 * Routes that are accessible without authentication.
+	 * These routes bypass all authentication checks.
+	 *
+	 * @default []
+	 */
+	publicRoutes?: RoutePattern[];
+
+	/**
+	 * Routes that require any authenticated user.
+	 * Users must be logged in but no specific permissions are required.
+	 *
+	 * @default []
+	 */
+	authenticatedRoutes?: RoutePattern[];
+
+	/**
+	 * Routes that require admin privileges.
+	 * Only users with isAdmin=true can access these routes.
+	 *
+	 * @default []
+	 */
+	adminRoutes?: RoutePattern[];
+
+	/**
+	 * Routes that require brand-specific access.
+	 * Users must have access to the specific brand ID extracted from the route,
+	 * or be an admin.
+	 *
+	 * @default []
+	 */
+	brandRoutes?: BrandRouteConfig[];
+
+	/**
+	 * URL to redirect to when authentication is required.
+	 * Query parameters will be added for return URL and error messages.
+	 *
+	 * @default '/login'
+	 */
+	loginUrl?: string;
+}
+
+/**
+ * Options for configuring the htlkg Astro integration.
+ *
+ * @example
+ * htlkg({
+ *   auth: {
+ *     publicRoutes: ['/login', '/'],
+ *     adminRoutes: [/^\/admin/],
+ *     loginUrl: '/login'
+ *   },
+ *   loginPage: {
+ *     logo: 'https://example.com/logo.png',
+ *     title: 'Admin Portal',
+ *     redirectUrl: '/admin/dashboard'
+ *   },
+ *   validateEnv: true,
+ *   tailwind: { configFile: './tailwind.config.mjs' }
+ * })
+ */
+export interface HtlkgIntegrationOptions {
+	/**
+	 * Route guard configuration for authentication and authorization.
+	 * Defines which routes are public, require authentication, or require
+	 * specific permissions.
+	 *
+	 * @default {}
+	 */
+	auth?: RouteGuardConfig;
+
+	/**
+	 * Configuration for the default login page.
+	 * Set to false to disable automatic login page injection.
+	 *
+	 * @default { path: '/login', title: 'Sign In', redirectUrl: '/admin' }
+	 */
+	loginPage?: LoginPageConfig | false;
+
+
+
+	/**
+	 * Validate that required environment variables are present.
+	 * When enabled, the integration will check for required Amplify
+	 * environment variables and log warnings if any are missing.
+	 *
+	 * @default true
+	 */
+	validateEnv?: boolean;
+
+	/**
+	 * List of required environment variable names to validate.
+	 * Only used when validateEnv is true.
+	 *
+	 * @default ['PUBLIC_COGNITO_USER_POOL_ID', 'PUBLIC_COGNITO_USER_POOL_CLIENT_ID']
+	 */
+	requiredEnvVars?: string[];
+
+	/**
+	 * AWS Amplify configuration.
+	 * Pass the amplify_outputs.json content directly for automatic configuration.
+	 * This is the recommended approach as it ensures consistency with Amplify CLI.
+	 *
+	 * @example
+	 * import amplifyOutputs from './amplify_outputs.json';
+	 * 
+	 * htlkg({
+	 *   amplify: amplifyOutputs
+	 * })
+	 */
+	amplify?: Record<string, unknown>;
+
+	/**
+	 * Tailwind CSS integration configuration.
+	 * Set to false to disable automatic Tailwind integration.
+	 * Pass an object to configure Tailwind options (e.g., configFile).
+	 *
+	 * @default undefined (Tailwind enabled with default config)
+	 */
+	tailwind?: Record<string, unknown> | false;
+}
+
+/**
+ * Type guard to check if a value is an authenticated user.
+ * Useful for narrowing types in TypeScript when checking user authentication.
+ *
+ * @param user - Value to check
+ * @returns True if the value is a valid AuthUser object
+ *
+ * @example
+ * if (isAuthenticatedUser(locals.user)) {
+ *   // TypeScript knows locals.user is AuthUser here
+ *   console.log(locals.user.email);
+ * }
+ */
+export function isAuthenticatedUser(user: unknown): user is AuthUser {
+	return (
+		user !== null &&
+		typeof user === 'object' &&
+		'username' in user &&
+		'email' in user &&
+		'brandIds' in user &&
+		'accountIds' in user &&
+		'isAdmin' in user &&
+		typeof (user as AuthUser).username === 'string' &&
+		typeof (user as AuthUser).email === 'string' &&
+		Array.isArray((user as AuthUser).brandIds) &&
+		Array.isArray((user as AuthUser).accountIds) &&
+		typeof (user as AuthUser).isAdmin === 'boolean'
+	);
+}

package/src/htlkg/index.ts

@@ -0,0 +1,245 @@
+/**
+ * htlkg Astro Integration
+ * 
+ * Provides zero-config setup for Hotelinking applications with:
+ * - Tailwind CSS integration
+ * - Vue 3 integration with Amplify setup
+ * - Authentication middleware
+ * - Route guards
+ * - Login page generation
+ */
+
+import tailwind from '@astrojs/tailwind';
+import vue from '@astrojs/vue';
+import type { AstroIntegration } from 'astro';
+import type { HtlkgIntegrationOptions } from './config.js';
+import { createVirtualModulePlugin, virtualModuleTypes } from './virtual-modules.js';
+
+/**
+ * Default environment variables required for AWS Amplify authentication
+ */
+const DEFAULT_ENV_VARS = [
+	'PUBLIC_COGNITO_USER_POOL_ID',
+	'PUBLIC_COGNITO_USER_POOL_CLIENT_ID'
+];
+
+/**
+ * htlkg Astro integration that provides zero-config authentication setup.
+ *
+ * This integration automatically:
+ * - Includes Tailwind CSS integration (can be disabled)
+ * - Includes Vue 3 integration with Amplify and Nanostores setup
+ * - Injects authentication middleware for AWS Amplify
+ * - Configures route guards based on declarative configuration
+ * - Validates required environment variables (optional)
+ * - Injects TypeScript types for Astro.locals.user
+ * - Provides a default login page (optional)
+ *
+ * @param options - Configuration options for the integration
+ * @returns Astro integration object or array of integrations
+ *
+ * @example
+ * // astro.config.mjs
+ * import { htlkg } from '@htlkg/astro';
+ *
+ * export default defineConfig({
+ *   integrations: [
+ *     htlkg({
+ *       tailwind: { configFile: './tailwind.config.mjs' },
+ *       auth: {
+ *         publicRoutes: ['/login', '/'],
+ *         adminRoutes: [/^\/admin/],
+ *         loginUrl: '/login'
+ *       }
+ *     })
+ *   ]
+ * });
+ */
+export function htlkg(
+	options: HtlkgIntegrationOptions = {},
+): AstroIntegration | AstroIntegration[] {
+	const {
+		auth = {},
+		loginPage = { path: '/login', title: 'Sign In', redirectUrl: '/admin' },
+		validateEnv = true,
+		requiredEnvVars = DEFAULT_ENV_VARS,
+		tailwind: tailwindOptions,
+		amplify,
+	} = options;
+
+	const integrations: AstroIntegration[] = [];
+
+	// Add Tailwind integration (enabled by default)
+	if (tailwindOptions !== false) {
+		const tailwindConfig =
+			typeof tailwindOptions === 'object' ? tailwindOptions : undefined;
+		integrations.push(
+			tailwind(tailwindConfig as Parameters<typeof tailwind>[0]),
+		);
+	}
+
+	// Add Vue integration with Amplify setup entrypoint
+	// Use package import specifier that Vite can resolve
+	integrations.push(
+		vue({
+			appEntrypoint: '@htlkg/astro/vue-app-setup',
+		}),
+	);
+
+	// Add the main htlkg integration
+	integrations.push({
+		name: '@htlkg/astro',
+		hooks: {
+			'astro:config:setup': ({
+				config,
+				updateConfig,
+				addMiddleware,
+				injectRoute,
+				logger,
+			}) => {
+				try {
+					// 1. Verify Vue integration is present
+					const hasVue = config.integrations.some(
+						(i) => i.name === '@astrojs/vue',
+					);
+					if (hasVue) {
+						logger.info('Vue integration configured with Amplify app setup');
+					}
+
+					// 2. Amplify will be configured by the middleware on first request
+					if (amplify) {
+						logger.info('Amplify configuration provided - will be configured on first request');
+					} else {
+						logger.info('No Amplify configuration provided - will use environment variables');
+					}
+
+					// 3. Validate environment variables (only if not using amplify_outputs.json)
+					if (validateEnv && !amplify) {
+						const missing = requiredEnvVars.filter(
+							(varName) => !process.env[varName],
+						);
+
+						if (missing.length > 0) {
+							logger.warn(
+								`Missing required environment variables: ${missing.join(', ')}\nAuthentication may not work correctly. Please set these in your .env file:\n${missing.map((v) => `  - ${v}`).join('\n')}`,
+							);
+						} else {
+							logger.info('All required environment variables are present');
+						}
+					}
+
+					// 4. Create Vite virtual module plugin to pass configuration to middleware and pages
+					try {
+						const virtualModulePlugin = createVirtualModulePlugin(
+							auth,
+							loginPage,
+							amplify || null
+						);
+
+						updateConfig({
+							vite: {
+								plugins: [virtualModulePlugin],
+							},
+						});
+					} catch (error) {
+						const errorMsg =
+							error instanceof Error ? error.message : 'Unknown error';
+						logger.error(
+							`Failed to create virtual module for route configuration: ${errorMsg}`,
+						);
+						throw error;
+					}
+
+					// 5. Inject middleware
+					try {
+						addMiddleware({
+							entrypoint: '@htlkg/astro/middleware',
+							order: 'pre',
+						});
+						logger.info('Authentication middleware injected successfully');
+					} catch (error) {
+						const errorMsg =
+							error instanceof Error ? error.message : 'Unknown error';
+						logger.error(`Failed to inject middleware: ${errorMsg}`);
+						throw error;
+					}
+
+					// 6. Verify Vue app entrypoint is configured
+					const vueIntegrationIndex = config.integrations.findIndex(
+						(i) => i.name === '@astrojs/vue',
+					);
+
+					if (vueIntegrationIndex === -1) {
+						logger.warn(
+							'@astrojs/vue integration not found.\n' +
+								'The htlkg integration should have added it automatically.\n' +
+								'If you see this warning, there may be an integration ordering issue.',
+						);
+					} else {
+						logger.info('Vue app setup with Amplify configuration enabled');
+					}
+
+					// 7. Verify Tailwind integration
+					const hasTailwind = config.integrations.some(
+						(i) =>
+							i.name === '@astrojs/tailwind' || i.name === 'astro:tailwind',
+					);
+
+					if (hasTailwind) {
+						logger.info('Tailwind CSS integration configured');
+					}
+
+					// 8. Inject login page route if enabled
+					if (loginPage !== false) {
+						try {
+							const loginPath = loginPage.path || '/login';
+							injectRoute({
+								pattern: loginPath,
+								entrypoint: '@htlkg/astro/auth/LoginPage.astro',
+								prerender: false,
+							});
+							logger.info(`Injected default login page at ${loginPath}`);
+						} catch (error) {
+							const errorMsg =
+								error instanceof Error ? error.message : 'Unknown error';
+							logger.warn(`Failed to inject login page: ${errorMsg}`);
+						}
+					}
+
+					logger.info('htlkg integration configured successfully');
+				} catch (error) {
+					const errorMsg =
+						error instanceof Error ? error.message : 'Unknown error';
+					logger.error(
+						`Failed to configure htlkg integration: ${errorMsg}`,
+					);
+					throw error;
+				}
+			},
+			'astro:config:done': ({ injectTypes }) => {
+				// Inject TypeScript types for Astro.locals and virtual module
+				injectTypes({
+					filename: 'htlkg.d.ts',
+					content: `
+import type { AuthUser } from '@htlkg/core/types';
+
+declare global {
+  namespace App {
+    interface Locals {
+      user: AuthUser | null;
+    }
+  }
+}
+
+${virtualModuleTypes}
+
+export {};
+`,
+				});
+			},
+		},
+	});
+
+	// Return single integration or array based on what was added
+	return integrations.length === 1 ? integrations[0] : integrations;
+}

package/src/htlkg/virtual-modules.test.ts

@@ -0,0 +1,158 @@
+/**
+ * Unit tests for virtual module setup
+ */
+
+import { describe, it, expect } from 'vitest';
+import { createVirtualModulePlugin } from './virtual-modules.js';
+
+describe('Virtual Module Plugin', () => {
+	it('should create a valid Vite plugin', () => {
+		const authConfig = {
+			publicRoutes: ['/login', '/'],
+			authenticatedRoutes: ['/dashboard'],
+			adminRoutes: [/^\/admin/],
+			brandRoutes: [],
+			loginUrl: '/login',
+		};
+
+		const plugin = createVirtualModulePlugin(authConfig, null, null);
+
+		expect(plugin).toBeDefined();
+		expect(plugin.name).toBe('htlkg-config');
+		expect(typeof plugin.resolveId).toBe('function');
+		expect(typeof plugin.load).toBe('function');
+	});
+
+	it('should resolve virtual module ID', () => {
+		const plugin = createVirtualModulePlugin({}, null, null);
+		
+		const resolved = plugin.resolveId('virtual:htlkg-config');
+		expect(resolved).toBe('\0virtual:htlkg-config');
+	});
+
+	it('should not resolve non-virtual module IDs', () => {
+		const plugin = createVirtualModulePlugin({}, null, null);
+		
+		const resolved = plugin.resolveId('some-other-module');
+		expect(resolved).toBeUndefined();
+	});
+
+	it('should generate module code with string patterns', () => {
+		const authConfig = {
+			publicRoutes: ['/login', '/register'],
+			authenticatedRoutes: ['/dashboard'],
+			adminRoutes: [],
+			brandRoutes: [],
+			loginUrl: '/login',
+		};
+
+		const plugin = createVirtualModulePlugin(authConfig, null, null);
+		const code = plugin.load('\0virtual:htlkg-config');
+
+		expect(code).toContain('publicRoutes: ["/login", "/register"]');
+		expect(code).toContain('authenticatedRoutes: ["/dashboard"]');
+		expect(code).toContain('loginUrl: "/login"');
+	});
+
+	it('should generate module code with RegExp patterns', () => {
+		const authConfig = {
+			publicRoutes: [],
+			authenticatedRoutes: [],
+			adminRoutes: [/^\/admin/],
+			brandRoutes: [],
+			loginUrl: '/login',
+		};
+
+		const plugin = createVirtualModulePlugin(authConfig, null, null);
+		const code = plugin.load('\0virtual:htlkg-config');
+
+		expect(code).toContain('new RegExp');
+		// The pattern is serialized as a string, so we check for the pattern source
+		expect(code).toContain('adminRoutes: [new RegExp(');
+	});
+
+	it('should generate module code with mixed patterns', () => {
+		const authConfig = {
+			publicRoutes: ['/login', /^\/public/],
+			authenticatedRoutes: ['/dashboard', /^\/app/],
+			adminRoutes: [],
+			brandRoutes: [],
+			loginUrl: '/login',
+		};
+
+		const plugin = createVirtualModulePlugin(authConfig, null, null);
+		const code = plugin.load('\0virtual:htlkg-config');
+
+		expect(code).toContain('"/login"');
+		expect(code).toContain('new RegExp');
+		expect(code).toContain('"/dashboard"');
+	});
+
+	it('should handle empty route arrays', () => {
+		const authConfig = {
+			publicRoutes: [],
+			authenticatedRoutes: [],
+			adminRoutes: [],
+			brandRoutes: [],
+			loginUrl: '/login',
+		};
+
+		const plugin = createVirtualModulePlugin(authConfig, null, null);
+		const code = plugin.load('\0virtual:htlkg-config');
+
+		expect(code).toContain('publicRoutes: []');
+		expect(code).toContain('authenticatedRoutes: []');
+		expect(code).toContain('adminRoutes: []');
+	});
+
+	it('should serialize amplify config when provided', () => {
+		const amplifyConfig = {
+			userPoolId: 'us-east-1_abc123',
+			userPoolClientId: 'abc123def456',
+			region: 'us-east-1',
+		};
+
+		const plugin = createVirtualModulePlugin({}, null, amplifyConfig);
+		const code = plugin.load('\0virtual:htlkg-config');
+
+		expect(code).toContain('amplifyConfig');
+		expect(code).toContain('userPoolId');
+		expect(code).toContain('us-east-1_abc123');
+	});
+
+	it('should set amplify config to null when not provided', () => {
+		const plugin = createVirtualModulePlugin({}, null, null);
+		const code = plugin.load('\0virtual:htlkg-config');
+
+		expect(code).toContain('amplifyConfig = null');
+	});
+
+	it('should serialize login page config when provided', () => {
+		const loginPageConfig = {
+			path: '/custom-login',
+			title: 'Custom Login',
+			redirectUrl: '/dashboard',
+		};
+
+		const plugin = createVirtualModulePlugin({}, loginPageConfig, null);
+		const code = plugin.load('\0virtual:htlkg-config');
+
+		expect(code).toContain('loginPageConfig');
+		expect(code).toContain('custom-login');
+		expect(code).toContain('Custom Login');
+	});
+
+	it('should set login page config to null when disabled', () => {
+		const plugin = createVirtualModulePlugin({}, false, null);
+		const code = plugin.load('\0virtual:htlkg-config');
+
+		expect(code).toContain('loginPageConfig = null');
+	});
+
+	it('should not load non-virtual module IDs', () => {
+		const plugin = createVirtualModulePlugin({}, null, null);
+		const code = plugin.load('some-other-module');
+
+		expect(code).toBeUndefined();
+	});
+});