@elyracode/laravel-starters 0.3.4

package/README.md

@@ -0,0 +1,77 @@
+# @elyracode/laravel-starters
+
+Fetch, analyze, and customize Laravel starter kits directly from GitHub inside Elyra.
+
+Based on the official [Laravel 13.x Starter Kits](https://laravel.com/docs/13.x/starter-kits).
+
+## Install
+
+```
+elyra install npm:@elyracode/laravel-starters
+```
+
+## What's included
+
+### Commands
+
+- `/laravel:starter` -- Interactive selector to browse and load official Laravel starter kits as reference context
+
+### Tools (auto-used by the agent)
+
+| Tool | Description |
+|------|-------------|
+| `fetch_laravel_starter` | Fetch an official Laravel starter kit as reference |
+| `fetch_github_repo` | Fetch any public GitHub repository as reference context |
+
+### Available Starter Kits
+
+| ID | Name | Stack | UI Library |
+|----|------|-------|------------|
+| `react` | Laravel React Starter Kit | Inertia 2 + React 19 + TypeScript | shadcn/ui |
+| `vue` | Laravel Vue Starter Kit | Inertia 2 + Vue 3 Composition API + TypeScript | shadcn-vue |
+| `svelte` | Laravel Svelte Starter Kit | Inertia 2 + Svelte 5 + TypeScript | shadcn-svelte |
+| `livewire` | Laravel Livewire Starter Kit | Livewire 4 + PHP | Flux UI |
+
+All kits include:
+- **Fortify authentication** (login, registration, password reset, email verification)
+- **Two-factor authentication** (TOTP)
+- **Teams support** (optional)
+- **WorkOS AuthKit** variant (social auth, passkeys, magic auth, SSO)
+- **Layout variants**: sidebar, header
+- **Auth layout variants**: simple, card, split
+- **Tailwind CSS 4**
+
+## Usage
+
+### Interactive
+```
+/laravel:starter
+```
+Opens a selector to pick a starter kit. The kit's source code is loaded as context so the agent can reference official patterns.
+
+### Automatic
+Just ask the agent:
+```
+> Set up auth following the Laravel Vue starter kit
+> I need teams support with the Livewire starter kit
+> Build a dashboard using the React starter kit patterns
+> Show me how the Svelte starter kit handles 2FA
+```
+
+The agent automatically uses `fetch_laravel_starter` to load the relevant kit as reference.
+
+### Custom repos
+The agent can also fetch any public GitHub repo:
+```
+> Fetch the livewire/flux repo and show me the modal component
+> Look at how laravel/fortify handles two-factor authentication
+```
+
+## How it works
+
+1. Fetches the repository tree via GitHub API (no cloning needed)
+2. Downloads relevant source files (PHP, Vue, Svelte, TS, JS, Blade, etc.)
+3. Feeds the code as context to the agent
+4. The agent uses the official code as reference for your customizations
+
+No GitHub token required for public repos.

package/extensions/index.ts

@@ -0,0 +1,172 @@
+import type { ExtensionAPI } from "@elyracode/coding-agent";
+import { Type } from "typebox";
+import { fetchRepoContents, formatAsContext, STARTER_KITS } from "./starters.js";
+
+export default function (elyra: ExtensionAPI): void {
+	// -- Command: /laravel:starter --
+	// Lists available starter kits and lets the user pick one
+	elyra.registerCommand("laravel:starter", {
+		description: "Browse and fetch Laravel starter kits as reference context",
+		handler: async (_args, ctx) => {
+			const options = STARTER_KITS.map((kit) => `${kit.name} [${kit.stack}]`);
+
+			const selected = await ctx.ui.select("Select a Laravel starter kit", options);
+			if (!selected) return;
+
+			const kit = STARTER_KITS.find((k) => `${k.name} [${k.stack}]` === selected);
+			if (!kit) return;
+
+			ctx.ui.notify(`Fetching ${kit.name} from GitHub...`, "info");
+
+			try {
+				const files = await fetchRepoContents(kit.repo, kit.branch);
+				const context = formatAsContext(kit, files);
+
+				elyra.sendUserMessage([
+					{
+						type: "text",
+						text:
+							`I've loaded the ${kit.name} starter kit as reference (${files.length} files from github.com/${kit.repo}).\n\n` +
+							`Stack: ${kit.stack}\nFeatures: ${kit.features.join(", ")}\n\n` +
+							`Use this as reference to help me scaffold or customize my project. ` +
+							`Ask me what I want to build or modify.`,
+					},
+					{ type: "text", text: context },
+				]);
+
+				ctx.ui.notify(`Loaded ${files.length} files from ${kit.name}`, "info");
+			} catch (error) {
+				const msg = error instanceof Error ? error.message : String(error);
+				ctx.ui.notify(`Failed to fetch starter kit: ${msg}`, "error");
+			}
+		},
+	});
+
+	// -- Tool: fetch_laravel_starter --
+	// The agent can call this tool to fetch a starter kit as reference
+	elyra.registerTool({
+		name: "fetch_laravel_starter",
+		label: "Fetch Laravel Starter Kit",
+		description:
+			"Fetch an official Laravel starter kit from GitHub as reference code. " +
+			"Use this when the user asks about Laravel auth, teams, 2FA, profile management, " +
+			"or wants to scaffold a Laravel project following official patterns. " +
+			"Available kits: react (React 19 + shadcn/ui), vue (Vue 3 + shadcn-vue), " +
+			"svelte (Svelte 5 + shadcn-svelte), livewire (Livewire 4 + Flux UI). " +
+			"All kits include Fortify auth, 2FA, teams, and WorkOS support.",
+		parameters: Type.Object({
+			kit_id: Type.String({
+				description: "The starter kit ID: react, vue, svelte, livewire",
+			}),
+		}),
+		execute: async (_toolCallId, params) => {
+			const kit = STARTER_KITS.find((k) => k.id === params.kit_id);
+			if (!kit) {
+				const available = STARTER_KITS.map((k) => k.id).join(", ");
+				return {
+					content: [{ type: "text", text: `Unknown kit ID: ${params.kit_id}. Available: ${available}` }],
+					details: {},
+				};
+			}
+
+			try {
+				const files = await fetchRepoContents(kit.repo, kit.branch);
+				const context = formatAsContext(kit, files);
+
+				const truncated =
+					context.length > 100000
+						? `${context.slice(0, 100000)}\n\n... (truncated, ${files.length} files total)`
+						: context;
+
+				return {
+					content: [{ type: "text", text: truncated }],
+					details: {
+						kit: kit.name,
+						stack: kit.stack,
+						fileCount: files.length,
+						features: kit.features,
+					},
+				};
+			} catch (error) {
+				const msg = error instanceof Error ? error.message : String(error);
+				return {
+					content: [{ type: "text", text: `Failed to fetch ${kit.name}: ${msg}` }],
+					details: {},
+				};
+			}
+		},
+	});
+
+	// -- Tool: fetch_github_repo --
+	// Generic tool to fetch any GitHub repo as reference
+	elyra.registerTool({
+		name: "fetch_github_repo",
+		label: "Fetch GitHub Repository",
+		description:
+			"Fetch source code from any public GitHub repository as reference context. " +
+			"Useful for studying implementation patterns, understanding libraries, " +
+			"or using official repos as scaffolding reference. " +
+			"Returns file contents filtered to code files (PHP, JS, TS, Vue, etc.).",
+		parameters: Type.Object({
+			repo: Type.String({
+				description: "GitHub owner/repo (e.g., 'laravel/framework', 'livewire/livewire')",
+			}),
+			branch: Type.Optional(Type.String({ description: "Branch name (default: main)" })),
+			path_filter: Type.Optional(
+				Type.String({
+					description: "Only include files under this path prefix (e.g., 'src/', 'stubs/')",
+				}),
+			),
+			max_files: Type.Optional(Type.Number({ description: "Maximum number of files to fetch (default: 100)" })),
+		}),
+		execute: async (_toolCallId, params) => {
+			try {
+				const branch = params.branch || "main";
+				const maxFiles = params.max_files || 100;
+
+				let files = await fetchRepoContents(params.repo, branch, { maxFiles });
+
+				if (params.path_filter) {
+					files = files.filter((f) => f.path.startsWith(params.path_filter!));
+				}
+
+				if (files.length === 0) {
+					return {
+						content: [{ type: "text", text: `No matching files found in ${params.repo}@${branch}` }],
+						details: {},
+					};
+				}
+
+				const lines: string[] = [
+					`# Repository: github.com/${params.repo} (${branch})`,
+					`Files: ${files.length}`,
+					"",
+				];
+				for (const file of files) {
+					lines.push(`## ${file.path}`);
+					lines.push("```");
+					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, ${files.length} files total)`
+						: context;
+
+				return {
+					content: [{ type: "text", text: truncated }],
+					details: { repo: params.repo, branch, fileCount: files.length },
+				};
+			} catch (error) {
+				const msg = error instanceof Error ? error.message : String(error);
+				return {
+					content: [{ type: "text", text: `Failed to fetch ${params.repo}: ${msg}` }],
+					details: {},
+				};
+			}
+		},
+	});
+}

package/extensions/starters.ts

@@ -0,0 +1,180 @@
+/**
+ * Laravel starter kit registry and GitHub repo fetching.
+ */
+
+export interface StarterKit {
+	id: string;
+	name: string;
+	description: string;
+	repo: string; // GitHub owner/repo
+	branch: string;
+	stack: string;
+	ui: string;
+	features: string[];
+	layouts: string[];
+	authLayouts: string[];
+}
+
+/**
+ * Official Laravel starter kits (Laravel 13.x).
+ * See: https://laravel.com/docs/13.x/starter-kits
+ */
+export const STARTER_KITS: StarterKit[] = [
+	{
+		id: "react",
+		name: "Laravel React Starter Kit",
+		description: "Inertia 2, React 19, TypeScript, Tailwind 4, shadcn/ui. Full auth with Fortify, 2FA, teams, WorkOS option.",
+		repo: "laravel/react-starter-kit",
+		branch: "main",
+		stack: "react",
+		ui: "shadcn/ui",
+		features: ["auth", "registration", "password-reset", "email-verification", "2fa", "teams", "workos"],
+		layouts: ["sidebar", "header"],
+		authLayouts: ["simple", "card", "split"],
+	},
+	{
+		id: "vue",
+		name: "Laravel Vue Starter Kit",
+		description: "Inertia 2, Vue 3 Composition API, TypeScript, Tailwind, shadcn-vue. Full auth with Fortify, 2FA, teams, WorkOS option.",
+		repo: "laravel/vue-starter-kit",
+		branch: "main",
+		stack: "VILT",
+		ui: "shadcn-vue",
+		features: ["auth", "registration", "password-reset", "email-verification", "2fa", "teams", "workos"],
+		layouts: ["sidebar", "header"],
+		authLayouts: ["simple", "card", "split"],
+	},
+	{
+		id: "svelte",
+		name: "Laravel Svelte Starter Kit",
+		description: "Inertia 2, Svelte 5, TypeScript, Tailwind, shadcn-svelte. Full auth with Fortify, 2FA, teams, WorkOS option.",
+		repo: "laravel/svelte-starter-kit",
+		branch: "main",
+		stack: "svelte",
+		ui: "shadcn-svelte",
+		features: ["auth", "registration", "password-reset", "email-verification", "2fa", "teams", "workos"],
+		layouts: ["sidebar", "header"],
+		authLayouts: ["simple", "card", "split"],
+	},
+	{
+		id: "livewire",
+		name: "Laravel Livewire Starter Kit",
+		description: "Livewire 4, Tailwind, Flux UI. Full auth with Fortify, 2FA, teams, WorkOS option.",
+		repo: "laravel/livewire-starter-kit",
+		branch: "main",
+		stack: "TALL",
+		ui: "Flux UI",
+		features: ["auth", "registration", "password-reset", "email-verification", "2fa", "teams", "workos"],
+		layouts: ["sidebar", "header"],
+		authLayouts: ["simple", "card", "split"],
+	},
+];
+
+export interface FetchedFile {
+	path: string;
+	content: string;
+}
+
+/**
+ * Fetch the contents of a GitHub repo directory tree via the GitHub API.
+ * Returns a flat list of file paths and their contents.
+ * Uses the GitHub trees API for efficiency (single request for the tree,
+ * then fetches individual files via raw.githubusercontent.com).
+ */
+export async function fetchRepoContents(
+	repo: string,
+	branch: string,
+	options?: { maxFiles?: number; extensions?: string[] },
+): Promise<FetchedFile[]> {
+	const maxFiles = options?.maxFiles ?? 200;
+	const extensions = options?.extensions ?? [
+		".php",
+		".blade.php",
+		".vue",
+		".ts",
+		".tsx",
+		".js",
+		".jsx",
+		".json",
+		".md",
+		".css",
+		".env.example",
+	];
+
+	// Fetch the repo tree
+	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-laravel-starters",
+		},
+	});
+
+	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 }>;
+	};
+
+	// Filter to relevant files
+	const relevantFiles = tree.tree
+		.filter((entry) => {
+			if (entry.type !== "blob") return false;
+			if (entry.size && entry.size > 100000) return false; // Skip files > 100KB
+			return extensions.some((ext) => entry.path.endsWith(ext));
+		})
+		.slice(0, maxFiles);
+
+	// Fetch file contents in parallel (batched to avoid rate limits)
+	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-laravel-starters" },
+				});
+				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);
+		}
+	}
+
+	return files;
+}
+
+/**
+ * Format fetched files as a context string for the agent's system prompt.
+ */
+export function formatAsContext(kit: StarterKit, files: FetchedFile[]): string {
+	const lines: string[] = [
+		`# Reference: ${kit.name}`,
+		`Repository: github.com/${kit.repo} (${kit.branch})`,
+		`Stack: ${kit.stack} | UI: ${kit.ui}`,
+		`Features: ${kit.features.join(", ")}`,
+		`Layouts: ${kit.layouts.join(", ")} | Auth layouts: ${kit.authLayouts.join(", ")}`,
+		"",
+		"The following files are from the official Laravel starter kit. Use them as reference",
+		"for architecture, patterns, and best practices. Adapt the code to the user's needs.",
+		"",
+	];
+
+	for (const file of files) {
+		lines.push(`## ${file.path}`);
+		lines.push("```");
+		lines.push(file.content);
+		lines.push("```");
+		lines.push("");
+	}
+
+	return lines.join("\n");
+}

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@elyracode/laravel-starters",
+  "version": "0.3.4",
+  "description": "Elyra extension for fetching, analyzing, and customizing Laravel starter kits from GitHub",
+  "type": "module",
+  "keywords": ["elyra-package", "laravel", "starter-kit", "breeze", "jetstream", "scaffolding"],
+  "license": "MIT",
+  "author": "Knut W. Horne",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kwhorne/elyra.git",
+    "directory": "packages/laravel-starters"
+  },
+  "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'"
+  }
+}