@elyracode/laravel-starters 0.3.5 → 0.4.0

package/README.md

@@ -21,6 +21,7 @@ elyra install npm:@elyracode/laravel-starters
 | Tool | Description |
 |------|-------------|
 | `fetch_laravel_starter` | Fetch an official Laravel starter kit as reference |
+| `apply_starter_files` | Write starter kit files directly to the project directory |
 | `fetch_github_repo` | Fetch any public GitHub repository as reference context |
 
 ### Available Starter Kits
@@ -75,3 +76,19 @@ The agent can also fetch any public GitHub repo:
 4. The agent uses the official code as reference for your customizations
 
 No GitHub token required for public repos.
+
+## Caching
+
+Fetched repos are cached at `~/.elyra/cache/github/` for 24 hours. Repeat fetches are instant and don't hit GitHub's API rate limits.
+
+## Apply to Disk
+
+The agent can write starter kit files directly into your project:
+
+```
+> Apply the Vue starter kit to my project, but skip package.json
+```
+
+The `apply_starter_files` tool supports:
+- **path_prefix**: Only apply files under a specific path (e.g., `resources/`)
+- **exclude**: Skip specific files (e.g., `package.json`, `composer.json`)

package/extensions/index.ts

@@ -1,6 +1,8 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
 import type { ExtensionAPI } from "@elyracode/coding-agent";
 import { Type } from "typebox";
-import { fetchRepoContents, formatAsContext, STARTER_KITS } from "./starters.js";
+import { type FetchedFile, fetchRepoContents, formatAsContext, STARTER_KITS } from "./starters.js";
 
 export default function (elyra: ExtensionAPI): void {
 	// -- Command: /laravel:starter --
@@ -97,6 +99,87 @@ export default function (elyra: ExtensionAPI): void {
 		},
 	});
 
+	// -- Tool: apply_starter_files --
+	// Write fetched starter kit files to disk
+	elyra.registerTool({
+		name: "apply_starter_files",
+		label: "Apply Starter Kit Files",
+		description:
+			"Write files from a Laravel starter kit directly into the project directory. " +
+			"Use this after fetching a starter kit when the user confirms they want the files applied. " +
+			"Files are written relative to the current working directory. " +
+			"Existing files will be overwritten. Creates directories as needed.",
+		parameters: Type.Object({
+			kit_id: Type.String({
+				description: "The starter kit ID: react, vue, svelte, livewire",
+			}),
+			path_prefix: Type.Optional(
+				Type.String({
+					description:
+						"Only apply files under this path prefix (e.g., 'resources/', 'app/Http/'). Omit to apply all files.",
+				}),
+			),
+			exclude: Type.Optional(
+				Type.Array(Type.String(), {
+					description: "File paths to exclude (e.g., ['package.json', 'composer.json'])",
+				}),
+			),
+		}),
+		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 {
+				let files = await fetchRepoContents(kit.repo, kit.branch);
+				const cwd = process.cwd();
+				const excludeSet = new Set(params.exclude ?? []);
+
+				if (params.path_prefix) {
+					files = files.filter((f) => f.path.startsWith(params.path_prefix!));
+				}
+				files = files.filter((f) => !excludeSet.has(f.path));
+
+				const written: string[] = [];
+				const skipped: string[] = [];
+
+				for (const file of files) {
+					try {
+						const targetPath = join(cwd, file.path);
+						const dir = dirname(targetPath);
+						if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+						writeFileSync(targetPath, file.content, "utf-8");
+						written.push(file.path);
+					} catch {
+						skipped.push(file.path);
+					}
+				}
+
+				const summary = [`Applied ${written.length} files from ${kit.name} to ${cwd}`];
+				if (skipped.length > 0) {
+					summary.push(`Skipped ${skipped.length} files: ${skipped.join(", ")}`);
+				}
+				summary.push("", "Written files:", ...written.map((f) => `  ${f}`));
+
+				return {
+					content: [{ type: "text", text: summary.join("\n") }],
+					details: { written: written.length, skipped: skipped.length },
+				};
+			} catch (error) {
+				const msg = error instanceof Error ? error.message : String(error);
+				return {
+					content: [{ type: "text", text: `Failed to apply ${kit.name}: ${msg}` }],
+					details: {},
+				};
+			}
+		},
+	});
+
 	// -- Tool: fetch_github_repo --
 	// Generic tool to fetch any GitHub repo as reference
 	elyra.registerTool({

package/extensions/starters.ts

@@ -1,7 +1,11 @@
 /**
- * Laravel starter kit registry and GitHub repo fetching.
+ * Laravel starter kit registry, GitHub repo fetching, and file-based caching.
  */
 
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
 export interface StarterKit {
 	id: string;
 	name: string;
@@ -101,6 +105,15 @@ export async function fetchRepoContents(
 		".env.example",
 	];
 
+	// Check cache first
+	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);
+	}
+
 	// Fetch the repo tree
 	const treeUrl = `https://api.github.com/repos/${repo}/git/trees/${branch}?recursive=1`;
 	const treeResponse = await fetch(treeUrl, {
@@ -149,9 +162,52 @@ export async function fetchRepoContents(
 		}
 	}
 
+	// Save to cache
+	saveToCache(repo, branch, files);
+
 	return files;
 }
 
+// ── Cache ──
+
+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
+	}
+}
+
 /**
  * Format fetched files as a context string for the agent's system prompt.
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elyracode/laravel-starters",
-  "version": "0.3.5",
+  "version": "0.4.0",
   "description": "Elyra extension for fetching, analyzing, and customizing Laravel starter kits from GitHub",
   "type": "module",
   "keywords": ["elyra-package", "laravel", "starter-kit", "breeze", "jetstream", "scaffolding"],