@useavalon/avalon 0.1.0

package/src/core/integrations/README.md

@@ -0,0 +1,282 @@
+# Integration System
+
+The Avalon integration system provides a modular, extensible architecture for framework integrations. Each framework (Preact, Vue, Solid, Svelte) is an independent package with its own versioning and dependencies.
+
+## Architecture
+
+```
+src/core/integrations/
+├── registry.ts          # Integration registry for managing loaded integrations
+├── loader.ts            # Dynamic integration loading with caching
+├── validator.ts         # Integration validation and compliance checking
+├── config-loader.ts     # Configuration file loading and parsing
+├── startup.ts           # System initialization and validation
+├── cli.ts               # CLI commands for managing integrations
+└── index.ts             # Public API exports
+```
+
+## Key Components
+
+### Registry (`registry.ts`)
+
+The `IntegrationRegistry` manages loaded framework integrations:
+
+```typescript
+import { registry } from "./src/core/integrations/registry.ts";
+
+// Load an integration
+const integration = await registry.load("preact");
+
+// Check if loaded
+if (registry.has("preact")) {
+  const preact = registry.get("preact");
+}
+
+// Get all loaded integrations
+const all = registry.getAll();
+```
+
+### Loader (`loader.ts`)
+
+Dynamic integration loading with caching:
+
+```typescript
+import { loadIntegration } from "./src/core/integrations/loader.ts";
+
+// Load integration (cached)
+const integration = await loadIntegration("vue");
+
+// Preload multiple integrations
+await preloadIntegrations(["preact", "vue", "solid"]);
+
+// Check if loaded
+if (isIntegrationLoaded("svelte")) {
+  // ...
+}
+```
+
+### Validator (`validator.ts`)
+
+Validate integrations against the required interface:
+
+```typescript
+import { validateIntegration } from "./src/core/integrations/validator.ts";
+
+const result = validateIntegration(integration);
+
+if (result.valid) {
+  console.log("Integration is valid");
+} else {
+  console.error("Errors:", result.errors);
+  console.warn("Warnings:", result.warnings);
+}
+```
+
+### Configuration (`config-loader.ts`)
+
+Load and parse `avalon.config.ts`:
+
+```typescript
+import { loadConfig } from "./src/core/integrations/config-loader.ts";
+
+const result = await loadConfig();
+
+if (result.found) {
+  console.log("Config:", result.config);
+  console.log("Path:", result.configPath);
+}
+```
+
+### Startup (`startup.ts`)
+
+Initialize the integration system:
+
+```typescript
+import { initializeIntegrations } from "./src/core/integrations/startup.ts";
+
+const result = await initializeIntegrations();
+
+if (result.success) {
+  console.log("Loaded:", result.loadedIntegrations);
+} else {
+  console.error("Errors:", result.errors);
+}
+```
+
+## Configuration
+
+Create an `avalon.config.ts` file in your project root:
+
+```typescript
+export default {
+  integrations: [
+    { name: "preact", enabled: true },
+    { name: "vue", enabled: true },
+    { name: "solid", enabled: true },
+    { name: "svelte", enabled: true },
+  ],
+  autoDiscoverIntegrations: true,
+  validateIntegrations: true,
+  showWarnings: true,
+};
+```
+
+See [Integration Configuration](../../../docs/integration-configuration.md) for full documentation.
+
+## CLI Commands
+
+```bash
+# List integrations
+deno run --allow-read --allow-env src/core/integrations/cli.ts list
+
+# Initialize system
+deno run --allow-read --allow-env src/core/integrations/cli.ts init
+
+# Validate integrations
+deno run --allow-read --allow-env src/core/integrations/cli.ts validate
+
+# Show integration info
+deno run --allow-read --allow-env src/core/integrations/cli.ts info preact
+
+# Generate config file
+deno run --allow-read --allow-write src/core/integrations/cli.ts generate-config
+```
+
+## Error Handling
+
+The system provides helpful error messages:
+
+### Missing Integration
+
+```typescript
+try {
+  await loadIntegration("vue");
+} catch (error) {
+  // Error includes installation instructions
+  console.error(error.message);
+}
+```
+
+### Validation Errors
+
+```typescript
+const result = validateIntegration(integration);
+
+if (!result.valid) {
+  // Detailed error messages
+  result.errors.forEach(error => console.error(error));
+}
+```
+
+### Configuration Errors
+
+```typescript
+const config = await loadConfig();
+
+if (config.errors.length > 0) {
+  // Configuration validation errors
+  config.errors.forEach(error => console.error(error));
+}
+```
+
+## Integration Discovery
+
+The system supports multiple discovery methods:
+
+### 1. Explicit Configuration
+
+List integrations in `avalon.config.ts`:
+
+```typescript
+export default {
+  integrations: [
+    { name: "preact", enabled: true },
+  ],
+};
+```
+
+### 2. Auto-Discovery
+
+Enable auto-discovery to load integrations based on usage:
+
+```typescript
+export default {
+  autoDiscoverIntegrations: true,
+};
+```
+
+### 3. Manual Loading
+
+Load integrations programmatically:
+
+```typescript
+import { loadIntegration } from "./src/core/integrations/loader.ts";
+
+const integration = await loadIntegration("solid");
+```
+
+## Validation
+
+Integrations are validated to ensure they implement the required interface:
+
+```typescript
+interface Integration {
+  name: string;
+  version: string;
+  render(params: RenderParams): Promise<RenderResult>;
+  getHydrationScript(): string;
+  config(): IntegrationConfig;
+  vitePlugin?(): any | any[];
+}
+```
+
+Validation checks:
+- Required properties exist and have correct types
+- Required methods are functions
+- Configuration is valid
+- Detection patterns are RegExp objects
+
+## Best Practices
+
+### Development
+
+```typescript
+export default {
+  autoDiscoverIntegrations: true,  // Flexible
+  validateIntegrations: true,       // Catch issues early
+  showWarnings: true,               // See all issues
+};
+```
+
+### Production
+
+```typescript
+export default {
+  integrations: [
+    // Only list what you use
+    { name: "preact", enabled: true },
+  ],
+  autoDiscoverIntegrations: false,  // Explicit control
+  validateIntegrations: true,       // Ensure compatibility
+  showWarnings: false,              // Clean logs
+};
+```
+
+## Testing
+
+Test the configuration system:
+
+```bash
+deno run --allow-read --allow-env src/core/integrations/test-config.ts
+```
+
+## API Reference
+
+See [Integration Configuration](../../../docs/integration-configuration.md) for complete API documentation.
+
+## Related Documentation
+
+- [Integration System Design](../../../.kiro/specs/framework-integrations/design.md)
+- [Integration Requirements](../../../.kiro/specs/framework-integrations/requirements.md)
+- [Integration Configuration](../../../docs/integration-configuration.md)
+- [Creating Custom Integrations](../../../docs/custom-integrations.md)

package/src/core/integrations/index.ts

@@ -0,0 +1,19 @@
+/**
+ * Integration system exports
+ * Central export point for all integration-related functionality
+ */
+
+// Registry
+export { IntegrationRegistry, registry } from "./registry.ts";
+
+// Loader
+export {
+  loadIntegration,
+  detectAndLoadIntegration,
+  detectFrameworkFromPath,
+  detectFrameworkFromContent,
+  preloadIntegrations,
+  getLoadedIntegrations,
+  clearIntegrationCache,
+  isIntegrationLoaded,
+} from "./loader.ts";

package/src/core/integrations/loader.ts

@@ -0,0 +1,125 @@
+import { registry } from "./registry.ts";
+import type { Integration } from "@useavalon/core";
+
+/**
+ * Cache for loaded integrations to avoid repeated dynamic imports
+ */
+const integrationCache = new Map<string, Integration>();
+
+/**
+ * Load an integration by name, using cache if available
+ */
+export async function loadIntegration(framework: string): Promise<Integration> {
+  // Check cache first
+  if (integrationCache.has(framework)) {
+    return integrationCache.get(framework)!;
+  }
+
+  // Load from registry (which handles dynamic imports)
+  const integration = await registry.load(framework);
+  
+  // Cache the loaded integration
+  integrationCache.set(framework, integration);
+  
+  return integration;
+}
+
+/**
+ * Detect framework from file path and load the appropriate integration
+ */
+export async function detectAndLoadIntegration(src: string): Promise<Integration> {
+  const framework = detectFrameworkFromPath(src);
+  return await loadIntegration(framework);
+}
+
+/**
+ * Detect framework from file path based on extension and naming conventions
+ */
+export function detectFrameworkFromPath(src: string): string {
+  // Vue files
+  if (src.endsWith(".vue")) {
+    return "vue";
+  }
+  
+  // Svelte files
+  if (src.endsWith(".svelte")) {
+    return "svelte";
+  }
+  
+  // Solid files (convention: .solid.tsx or .solid.jsx)
+  if (src.includes(".solid.")) {
+    return "solid";
+  }
+  
+  // Qwik files (convention: .qwik.tsx or .qwik.jsx)
+  if (src.includes(".qwik.")) {
+    return "qwik";
+  }
+  
+  // Default to Preact for .tsx and .jsx files
+  return "preact";
+}
+
+/**
+ * Detect framework from file content by analyzing imports and patterns
+ */
+export function detectFrameworkFromContent(
+  src: string,
+  content?: string
+): string {
+  // First try path-based detection
+  const pathFramework = detectFrameworkFromPath(src);
+  
+  // If we have a definitive answer from path, use it
+  if (pathFramework !== "preact" || !content) {
+    return pathFramework;
+  }
+  
+  // For .tsx/.jsx files, analyze content to distinguish between Preact and Solid
+  if (content.includes("solid-js")) {
+    return "solid";
+  }
+  
+  if (content.includes("@builder.io/qwik")) {
+    return "qwik";
+  }
+  
+  if (content.includes("preact")) {
+    return "preact";
+  }
+  
+  // Default to Preact
+  return "preact";
+}
+
+/**
+ * Preload integrations for the given frameworks
+ * Useful for warming up the cache during build or startup
+ */
+export async function preloadIntegrations(frameworks: string[]): Promise<void> {
+  await Promise.all(
+    frameworks.map(framework => loadIntegration(framework))
+  );
+}
+
+/**
+ * Get all currently loaded integrations
+ */
+export function getLoadedIntegrations(): Integration[] {
+  return Array.from(integrationCache.values());
+}
+
+/**
+ * Clear the integration cache
+ * Useful for testing or hot module replacement
+ */
+export function clearIntegrationCache(): void {
+  integrationCache.clear();
+}
+
+/**
+ * Check if an integration is loaded in cache
+ */
+export function isIntegrationLoaded(framework: string): boolean {
+  return integrationCache.has(framework);
+}

package/src/core/integrations/registry.ts

@@ -0,0 +1,195 @@
+import type { Integration } from "@useavalon/core";
+import { dirname, join } from "node:path";
+import { statSync } from "node:fs";
+
+/**
+ * Find the root of the Avalon monorepo by looking for packages/integrations
+ */
+function findMonorepoRoot(): string {
+  let currentDir = process.cwd();
+
+  // Walk up the directory tree looking for packages/integrations
+  for (let i = 0; i < 10; i++) {
+    try {
+      const integrationsPath = join(currentDir, "packages", "integrations");
+      const stat = statSync(integrationsPath);
+      if (stat.isDirectory()) {
+        return currentDir;
+      }
+    } catch {
+      // Directory doesn't exist, try parent
+    }
+
+    const parent = dirname(currentDir);
+    if (parent === currentDir) {
+      // Reached root, stop
+      break;
+    }
+    currentDir = parent;
+  }
+
+  // Fallback to cwd
+  return process.cwd();
+}
+
+/**
+ * IntegrationRegistry manages loaded framework integrations.
+ * It provides registration, retrieval, and dynamic loading of integrations.
+ */
+export class IntegrationRegistry {
+  private readonly integrations = new Map<string, Integration>();
+  private readonly loadingPromises = new Map<string, Promise<Integration>>();
+
+  /**
+   * Register an integration instance
+   */
+  register(integration: Integration): void {
+    if (!integration.name) {
+      throw new Error("Integration must have a name");
+    }
+    this.integrations.set(integration.name, integration);
+  }
+
+  /**
+   * Get a registered integration by name
+   */
+  get(name: string): Integration | undefined {
+    return this.integrations.get(name);
+  }
+
+  /**
+   * Check if an integration is registered
+   */
+  has(name: string): boolean {
+    return this.integrations.has(name);
+  }
+
+  /**
+   * Dynamically load an integration by name
+   * Returns cached integration if already loaded
+   */
+  async load(name: string): Promise<Integration> {
+    // Check if already loaded
+    const existing = this.integrations.get(name);
+    if (existing) {
+      return existing;
+    }
+
+    // Check if currently loading (prevent duplicate loads)
+    const loadingPromise = this.loadingPromises.get(name);
+    if (loadingPromise) {
+      return loadingPromise;
+    }
+
+    // Start loading
+    const promise = this.loadIntegration(name);
+    this.loadingPromises.set(name, promise);
+
+    try {
+      const integration = await promise;
+      this.register(integration);
+      return integration;
+    } finally {
+      this.loadingPromises.delete(name);
+    }
+  }
+
+  /**
+   * Internal method to load integration module
+   * Note: In development mode, integrations should be pre-loaded via preloader.ts
+   * before Vite's SSR context starts. This method is a fallback for production
+   * or when integrations weren't pre-loaded.
+   */
+  private async loadIntegration(name: string): Promise<Integration> {
+    try {
+      // Use absolute file:// URL to bypass Vite's module resolution
+      // This ensures we use Deno's native import which handles npm: specifiers correctly
+      const monorepoRoot = findMonorepoRoot();
+      const integrationPath = join(monorepoRoot, "packages", "integrations", name, "mod.ts");
+      const fileUrl = `file://${integrationPath}`;
+      
+      // Dynamic import with file:// URL bypasses Vite's SSR module loader
+      const module = await import(/* @vite-ignore */ fileUrl);
+      
+      // Look for the integration export (e.g., preactIntegration)
+      const integrationKey = `${name}Integration`;
+      const integration = module[integrationKey] || module.default;
+
+      if (!integration) {
+        throw new Error(
+          `Integration module '${name}' does not export '${integrationKey}' or a default export`
+        );
+      }
+
+      return integration as Integration;
+    } catch (error) {
+      // Check if this is a Vite SSR context issue
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      const isViteIssue = errorMessage.includes('ERR_UNSUPPORTED_ESM_URL_SCHEME') ||
+                          errorMessage.includes('Only file and data URLs are supported');
+      
+      if (isViteIssue) {
+        throw new Error(
+          `Integration '${name}' could not be loaded within Vite's SSR context. ` +
+          `This usually means the integration wasn't pre-loaded at server startup. ` +
+          `Make sure preloadIntegrationsNative() is called before Vite server starts.`,
+          { cause: error }
+        );
+      }
+      
+      throw new Error(
+        `Failed to load integration for framework '${name}'. ` +
+        `Make sure @useavalon/${name} is installed.\n` +
+        `Install it with: bun add @useavalon/${name}`,
+        { cause: error }
+      );
+    }
+  }
+
+  /**
+   * Get all registered integrations
+   */
+  getAll(): Integration[] {
+    return Array.from(this.integrations.values());
+  }
+
+  /**
+   * Get all registered integration names
+   */
+  getAllNames(): string[] {
+    return Array.from(this.integrations.keys());
+  }
+
+  /**
+   * Unregister an integration
+   */
+  unregister(name: string): boolean {
+    return this.integrations.delete(name);
+  }
+
+  /**
+   * Clear all registered integrations
+   */
+  clear(): void {
+    this.integrations.clear();
+    this.loadingPromises.clear();
+  }
+
+  /**
+   * Get the count of registered integrations
+   */
+  get size(): number {
+    return this.integrations.size;
+  }
+}
+
+// Global singleton registry instance
+// Use globalThis to ensure the registry is shared across all module contexts
+// This is important because Vite's ssrLoadModule creates new module contexts
+declare global {
+  var __avalonIntegrationRegistry: IntegrationRegistry | undefined;
+}
+
+globalThis.__avalonIntegrationRegistry ??= new IntegrationRegistry();
+
+export const registry = globalThis.__avalonIntegrationRegistry;