@elyracode/flux-ui 0.3.7

package/README.md

@@ -0,0 +1,57 @@
+# @elyracode/flux-ui
+
+Elyra extension for **Flux UI** -- live component index, Blade-to-Flux converter, and page generator for Livewire 4 projects.
+
+## Install
+
+```
+elyra install npm:@elyracode/flux-ui
+```
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `flux_component_index` | Fetch the live Flux UI component library from GitHub. Always up-to-date, cached for 24h. |
+| `blade_to_flux` | Analyze a Blade file and suggest Flux UI component replacements. |
+| `flux_generate_page` | Generate a complete page scaffold: Blade view, Livewire component, migration, route. |
+
+## Commands
+
+- `/flux` -- Interactive selector for all Flux UI tools
+
+## Usage
+
+### Live Component Reference
+```
+> Show me all available Flux UI components
+> What props does flux:table support?
+> Show me the flux:modal component API
+```
+
+The agent fetches the actual Flux UI source code from GitHub, so it always has the latest component APIs -- even components added yesterday.
+
+### Convert Existing Views
+```
+> Convert resources/views/users/index.blade.php to use Flux UI
+> Analyze my dashboard view for Flux conversion opportunities
+```
+
+The agent scans your Blade file, identifies HTML/Tailwind patterns (tables, forms, modals, buttons), and suggests specific Flux replacements.
+
+### Generate New Pages
+```
+> Generate a products CRUD page with Flux UI
+> Create a user settings page with profile form and password change
+> Build a dashboard with stats cards and a recent orders table
+```
+
+The agent generates all four files: Blade view with Flux components, Livewire class with validation, migration, and route.
+
+## How It Works
+
+1. **Component Index**: Fetches `livewire/flux` from GitHub, filters to component files, extracts props and slots
+2. **Blade Converter**: Pattern-matches 15+ HTML elements against Flux equivalents (button, input, select, table, modal, tabs, card, dropdown, breadcrumb, tooltip, switch, sidebar, header)
+3. **Page Generator**: Fetches the component index for accurate API usage, then provides structured generation instructions with Livewire 4 best practices (#[Validate], #[Computed], #[Url])
+
+All GitHub fetches are cached at `~/.elyra/cache/github/` for 24 hours.

package/extensions/github-fetch.ts

@@ -0,0 +1,116 @@
+/**
+ * GitHub repo fetching with file-based caching.
+ * Self-contained -- no dependency on @elyracode/laravel-starters.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export interface FetchedFile {
+	path: string;
+	content: string;
+}
+
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
+
+interface CacheEntry {
+	timestamp: number;
+	files: FetchedFile[];
+}
+
+function getCacheDir(): string {
+	return join(homedir(), ".elyra", "cache", "github");
+}
+
+function getCacheKey(repo: string, branch: string): string {
+	return `${repo.replace(/\//g, "--")}@${branch}.json`;
+}
+
+function loadFromCache(repo: string, branch: string): FetchedFile[] | undefined {
+	try {
+		const cachePath = join(getCacheDir(), getCacheKey(repo, branch));
+		if (!existsSync(cachePath)) return undefined;
+		const entry = JSON.parse(readFileSync(cachePath, "utf-8")) as CacheEntry;
+		if (Date.now() - entry.timestamp > CACHE_TTL_MS) return undefined;
+		return entry.files;
+	} catch {
+		return undefined;
+	}
+}
+
+function saveToCache(repo: string, branch: string, files: FetchedFile[]): void {
+	try {
+		const dir = getCacheDir();
+		if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+		const entry: CacheEntry = { timestamp: Date.now(), files };
+		writeFileSync(join(dir, getCacheKey(repo, branch)), JSON.stringify(entry));
+	} catch {
+		// Never fail on cache write errors
+	}
+}
+
+export async function fetchRepoContents(
+	repo: string,
+	branch: string,
+	options?: { maxFiles?: number; extensions?: string[] },
+): Promise<FetchedFile[]> {
+	const maxFiles = options?.maxFiles ?? 300;
+	const extensions = options?.extensions ?? [".php", ".blade.php", ".js", ".json"];
+
+	const cached = loadFromCache(repo, branch);
+	if (cached) {
+		let files = cached;
+		files = files.filter((f) => extensions.some((ext) => f.path.endsWith(ext)));
+		files = files.filter((f) => f.content.length <= 100000);
+		return files.slice(0, maxFiles);
+	}
+
+	const treeUrl = `https://api.github.com/repos/${repo}/git/trees/${branch}?recursive=1`;
+	const treeResponse = await fetch(treeUrl, {
+		headers: {
+			Accept: "application/vnd.github.v3+json",
+			"User-Agent": "elyra-flux-ui",
+		},
+	});
+
+	if (!treeResponse.ok) {
+		throw new Error(`GitHub API error: ${treeResponse.status} ${treeResponse.statusText}`);
+	}
+
+	const tree = (await treeResponse.json()) as {
+		tree: Array<{ path: string; type: string; size?: number }>;
+	};
+
+	const relevantFiles = tree.tree
+		.filter((entry) => {
+			if (entry.type !== "blob") return false;
+			if (entry.size && entry.size > 100000) return false;
+			return extensions.some((ext) => entry.path.endsWith(ext));
+		})
+		.slice(0, maxFiles);
+
+	const batchSize = 10;
+	const files: FetchedFile[] = [];
+
+	for (let i = 0; i < relevantFiles.length; i += batchSize) {
+		const batch = relevantFiles.slice(i, i + batchSize);
+		const results = await Promise.all(
+			batch.map(async (entry) => {
+				const rawUrl = `https://raw.githubusercontent.com/${repo}/${branch}/${entry.path}`;
+				const response = await fetch(rawUrl, {
+					headers: { "User-Agent": "elyra-flux-ui" },
+				});
+				if (!response.ok) return null;
+				const content = await response.text();
+				return { path: entry.path, content };
+			}),
+		);
+		for (const result of results) {
+			if (result) files.push(result);
+		}
+	}
+
+	saveToCache(repo, branch, files);
+	return files;
+}

package/extensions/index.ts

@@ -0,0 +1,318 @@
+import { readFileSync } from "node:fs";
+import type { ExtensionAPI } from "@elyracode/coding-agent";
+import { Type } from "typebox";
+import { fetchRepoContents } from "./github-fetch.js";
+
+const FLUX_REPO = "livewire/flux";
+const FLUX_BRANCH = "main";
+
+export default function (elyra: ExtensionAPI): void {
+
+	// ── Tool 1: flux_component_index ──
+	// Fetches the actual Flux UI source from GitHub and builds a live component reference
+	elyra.registerTool({
+		name: "flux_component_index",
+		label: "Flux UI Component Index",
+		description:
+			"Fetch the live Flux UI component library from GitHub and return a structured index of all available components, " +
+			"their props, slots, and variants. Always use this before generating Flux UI code to ensure you have the latest API. " +
+			"Results are cached for 24 hours.",
+		parameters: Type.Object({
+			component: Type.Optional(
+				Type.String({
+					description:
+						"Filter to a specific component name (e.g., 'button', 'modal', 'table'). Omit to get the full index.",
+				}),
+			),
+		}),
+		execute: async (_toolCallId, params) => {
+			try {
+				const files = await fetchRepoContents(FLUX_REPO, FLUX_BRANCH, {
+					extensions: [".blade.php", ".php"],
+					maxFiles: 300,
+				});
+
+				// Find component files (typically in stubs/ or src/components/)
+				let componentFiles = files.filter(
+					(f) =>
+						f.path.includes("stubs/") ||
+						f.path.includes("components/") ||
+						f.path.includes("views/"),
+				);
+
+				if (params.component) {
+					const search = params.component.toLowerCase();
+					componentFiles = componentFiles.filter(
+						(f) => f.path.toLowerCase().includes(search),
+					);
+				}
+
+				if (componentFiles.length === 0) {
+					return {
+						content: [
+							{
+								type: "text" as const,
+								text: params.component
+									? `No Flux UI component matching "${params.component}" found in ${FLUX_REPO}.`
+									: `No component files found in ${FLUX_REPO}. The repo structure may have changed.`,
+							},
+						],
+						details: {},
+					};
+				}
+
+				const lines: string[] = [
+					`# Flux UI Component Index (live from github.com/${FLUX_REPO})`,
+					`Components found: ${componentFiles.length}`,
+					"",
+					"Use these as the authoritative reference for Flux UI component APIs.",
+					"",
+				];
+
+				for (const file of componentFiles) {
+					lines.push(`## ${file.path}`);
+					lines.push("```blade");
+					lines.push(file.content);
+					lines.push("```");
+					lines.push("");
+				}
+
+				const context = lines.join("\n");
+				const truncated =
+					context.length > 100000
+						? `${context.slice(0, 100000)}\n\n... (truncated, ${componentFiles.length} files total)`
+						: context;
+
+				return {
+					content: [{ type: "text" as const, text: truncated }],
+					details: { componentCount: componentFiles.length },
+				};
+			} catch (error) {
+				const msg = error instanceof Error ? error.message : String(error);
+				return {
+					content: [{ type: "text" as const, text: `Failed to fetch Flux UI components: ${msg}` }],
+					details: {},
+				};
+			}
+		},
+	});
+
+	// ── Tool 2: blade_to_flux ──
+	// Reads a Blade file and suggests Flux component replacements
+	elyra.registerTool({
+		name: "blade_to_flux",
+		label: "Convert Blade to Flux UI",
+		description:
+			"Read a Blade view file and analyze it for HTML/Tailwind patterns that can be replaced with Flux UI components. " +
+			"Returns the original code alongside specific conversion suggestions. " +
+			"Use this when the user wants to modernize existing Blade views with Flux UI.",
+		parameters: Type.Object({
+			file_path: Type.String({
+				description: "Path to the Blade file to analyze (relative to cwd)",
+			}),
+		}),
+		execute: async (_toolCallId, params) => {
+			try {
+				const content = readFileSync(params.file_path, "utf-8");
+
+				// Pattern matching for common HTML -> Flux conversions
+				const suggestions: string[] = [];
+
+				const patterns: Array<{ pattern: RegExp; flux: string; description: string }> = [
+					{ pattern: /<button[\s>]/gi, flux: "<flux:button>", description: "Replace <button> with <flux:button>" },
+					{ pattern: /<input[\s>]/gi, flux: "<flux:input>", description: "Replace <input> with <flux:input>" },
+					{ pattern: /<select[\s>]/gi, flux: "<flux:select>", description: "Replace <select> with <flux:select>" },
+					{ pattern: /<textarea[\s>]/gi, flux: "<flux:textarea>", description: "Replace <textarea> with <flux:textarea>" },
+					{ pattern: /<table[\s>]/gi, flux: "<flux:table>", description: "Replace <table> with <flux:table> + <flux:columns> + <flux:rows>" },
+					{ pattern: /<dialog[\s>]|x-data=.*modal|x-show=.*modal/gi, flux: "<flux:modal>", description: "Replace modal pattern with <flux:modal>" },
+					{ pattern: /<nav[\s>].*tab|role="tablist"/gi, flux: "<flux:tabs>", description: "Replace tab navigation with <flux:tabs>" },
+					{ pattern: /<div.*class=".*card.*"/gi, flux: "<flux:card>", description: "Replace card div with <flux:card>" },
+					{ pattern: /class=".*badge.*"/gi, flux: "<flux:badge>", description: "Replace badge with <flux:badge>" },
+					{ pattern: /<div.*class=".*dropdown.*"|x-data=.*dropdown/gi, flux: "<flux:dropdown>", description: "Replace dropdown with <flux:dropdown>" },
+					{ pattern: /<div.*class=".*breadcrumb.*"/gi, flux: "<flux:breadcrumbs>", description: "Replace breadcrumb with <flux:breadcrumbs>" },
+					{ pattern: /<div.*class=".*tooltip.*"|x-data=.*tooltip/gi, flux: "<flux:tooltip>", description: "Replace tooltip with <flux:tooltip>" },
+					{ pattern: /<div.*class=".*switch.*"|type="checkbox".*role="switch"/gi, flux: "<flux:switch>", description: "Replace switch/toggle with <flux:switch>" },
+					{ pattern: /<header[\s>]/gi, flux: "<flux:header>", description: "Consider <flux:header> for page headers" },
+					{ pattern: /<aside[\s>]|class=".*sidebar.*"/gi, flux: "<flux:sidebar>", description: "Consider <flux:sidebar> for side navigation" },
+				];
+
+				for (const { pattern, description } of patterns) {
+					const matches = content.match(pattern);
+					if (matches) {
+						suggestions.push(`- ${description} (${matches.length} occurrence${matches.length > 1 ? "s" : ""})`);
+					}
+				}
+
+				// Check for wire:model patterns that could use Flux form components
+				const wireModels = content.match(/wire:model[.\w]*/g);
+				if (wireModels) {
+					suggestions.push(`- ${wireModels.length} wire:model binding(s) found -- ensure Flux form components use wire:model directly`);
+				}
+
+				const result: string[] = [
+					`# Blade to Flux UI Analysis: ${params.file_path}`,
+					"",
+				];
+
+				if (suggestions.length === 0) {
+					result.push("No obvious conversion opportunities found. The file may already use Flux UI or contain custom components.");
+				} else {
+					result.push(`Found ${suggestions.length} conversion opportunities:`, "");
+					result.push(...suggestions);
+					result.push("");
+					result.push("## Original source");
+					result.push("```blade");
+					result.push(content);
+					result.push("```");
+					result.push("");
+					result.push("To convert, use the flux_component_index tool to get the exact Flux API, then rewrite the file.");
+				}
+
+				return {
+					content: [{ type: "text" as const, text: result.join("\n") }],
+					details: { suggestions: suggestions.length },
+				};
+			} catch (error) {
+				const msg = error instanceof Error ? error.message : String(error);
+				return {
+					content: [{ type: "text" as const, text: `Failed to read ${params.file_path}: ${msg}` }],
+					details: {},
+				};
+			}
+		},
+	});
+
+	// ── Tool 3: flux_generate_page ──
+	// Generates a complete Flux UI page with Livewire component, migration, and routing
+	elyra.registerTool({
+		name: "flux_generate_page",
+		label: "Generate Flux UI Page",
+		description:
+			"Generate a complete Flux UI page scaffold including: Blade view with Flux components, " +
+			"Livewire component class, database migration, and route definition. " +
+			"First fetches the live Flux component index to ensure accurate component usage. " +
+			"Use this when the user wants to create a new page or feature in a TALL stack project.",
+		parameters: Type.Object({
+			page_name: Type.String({
+				description: "Name of the page/feature (e.g., 'products', 'user-settings', 'dashboard')",
+			}),
+			description: Type.String({
+				description:
+					"Description of what the page should do (e.g., 'CRUD table for products with name, price, category columns, edit dialog, and delete confirmation')",
+			}),
+			layout: Type.Optional(
+				Type.Union([Type.Literal("sidebar"), Type.Literal("header")], {
+					description: "Layout variant: sidebar (default) or header",
+				}),
+			),
+		}),
+		execute: async (_toolCallId, params) => {
+			try {
+				// Fetch Flux component index for accurate API usage
+				const files = await fetchRepoContents(FLUX_REPO, FLUX_BRANCH, {
+					extensions: [".blade.php"],
+					maxFiles: 200,
+				});
+
+				const componentFiles = files.filter(
+					(f) =>
+						f.path.includes("stubs/") ||
+						f.path.includes("components/") ||
+						f.path.includes("views/"),
+				);
+
+				// Build compact component reference (just names and key props)
+				const componentIndex: string[] = [
+					"# Available Flux UI Components (from source)",
+					"",
+				];
+
+				for (const file of componentFiles.slice(0, 50)) {
+					const name = file.path.split("/").pop()?.replace(".blade.php", "") ?? file.path;
+					// Extract @props from the component
+					const propsMatch = file.content.match(/@props\s*\(\s*\[([\s\S]*?)\]\s*\)/);
+					const props = propsMatch ? propsMatch[1].trim() : "";
+					componentIndex.push(`- flux:${name}${props ? ` (props: ${props.slice(0, 200)})` : ""}`);
+				}
+
+				const layout = params.layout ?? "sidebar";
+
+				const result: string[] = [
+					`# Page Generation Context: ${params.page_name}`,
+					"",
+					`Description: ${params.description}`,
+					`Layout: ${layout}`,
+					"",
+					"## Instructions",
+					"",
+					"Generate the following files for a TALL stack project:",
+					"",
+					`1. **Blade view**: \`resources/views/livewire/${params.page_name}.blade.php\``,
+					"   - Use Flux UI components (flux:table, flux:button, flux:modal, flux:input, etc.)",
+					`   - Use the ${layout} layout`,
+					"   - Include wire:model bindings for all form fields",
+					"   - Include wire:click for actions",
+					"",
+					`2. **Livewire component**: \`app/Livewire/${toPascalCase(params.page_name)}.php\``,
+					"   - Use #[Validate] for form validation",
+					"   - Use #[Computed] for expensive queries",
+					"   - Use #[Url] for filterable/sortable parameters",
+					"   - Include proper public properties for form state",
+					"",
+					`3. **Migration**: \`database/migrations/xxxx_create_${toSnakeCase(params.page_name)}_table.php\``,
+					"   - Based on the description, create appropriate columns",
+					"",
+					`4. **Route**: Add to \`routes/web.php\``,
+					`   - \`Route::get('/${params.page_name}', ${toPascalCase(params.page_name)}::class)->name('${params.page_name}')\``,
+					"",
+					...componentIndex,
+				];
+
+				return {
+					content: [{ type: "text" as const, text: result.join("\n") }],
+					details: { pageName: params.page_name, layout, componentCount: componentFiles.length },
+				};
+			} catch (error) {
+				const msg = error instanceof Error ? error.message : String(error);
+				return {
+					content: [{ type: "text" as const, text: `Failed to prepare page generation: ${msg}` }],
+					details: {},
+				};
+			}
+		},
+	});
+
+	// ── Command: /flux ──
+	elyra.registerCommand("flux", {
+		description: "Flux UI tools: component index, blade converter, page generator",
+		handler: async (_args, ctx) => {
+			const options = [
+				"Component Index -- fetch live Flux UI component reference",
+				"Blade to Flux -- analyze a Blade file for conversion opportunities",
+				"Generate Page -- scaffold a complete Flux UI page",
+			];
+
+			const selected = await ctx.ui.select("Flux UI Tools", options);
+			if (!selected) return;
+
+			if (selected.startsWith("Component Index")) {
+				elyra.sendUserMessage("Fetch the Flux UI component index and show me the available components.");
+			} else if (selected.startsWith("Blade to Flux")) {
+				elyra.sendUserMessage("I want to convert a Blade view to use Flux UI components. Ask me which file to analyze.");
+			} else if (selected.startsWith("Generate Page")) {
+				elyra.sendUserMessage("I want to generate a new Flux UI page. Ask me what the page should do.");
+			}
+		},
+	});
+}
+
+function toPascalCase(str: string): string {
+	return str
+		.split(/[-_\s]+/)
+		.map((word) => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase())
+		.join("");
+}
+
+function toSnakeCase(str: string): string {
+	return str.replace(/[-\s]+/g, "_").toLowerCase();
+}

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@elyracode/flux-ui",
+  "version": "0.3.7",
+  "description": "Elyra extension for Flux UI -- live component index, Blade-to-Flux converter, and page generator",
+  "type": "module",
+  "keywords": ["elyra-package", "flux-ui", "livewire", "laravel", "blade", "tailwind"],
+  "license": "MIT",
+  "author": "Knut W. Horne",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kwhorne/elyra.git",
+    "directory": "packages/flux-ui"
+  },
+  "elyra": {
+    "extensions": ["./extensions/index.ts"]
+  },
+  "peerDependencies": {
+    "@elyracode/coding-agent": "*",
+    "typebox": "*"
+  },
+  "scripts": {
+    "clean": "echo 'nothing to clean'",
+    "build": "echo 'nothing to build'",
+    "check": "echo 'nothing to check'"
+  }
+}