@lavralabs/lavra 0.7.0

package/scripts/convert-gemini.ts

@@ -0,0 +1,369 @@
+#!/usr/bin/env bun
+
+/**
+ * convert-gemini.ts
+ * Converts lavra plugin files from Claude Code format to Gemini CLI format
+ *
+ * Security controls:
+ * - Path traversal protection
+ * - File size limits (10MB)
+ * - YAML SAFE_SCHEMA parsing
+ * - Template injection prevention (escape {{ }})
+ * - Model name validation
+ * - Explicit file permissions (644)
+ */
+
+import { readdir, mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import {
+  validatePath,
+  sanitizeFilename,
+  readFileSafe,
+  writeFileSafe,
+  validateModelName,
+  validateFilename,
+} from "./shared/security";
+import {
+  parseFrontmatter,
+  extractBody,
+  buildMarkdown,
+} from "./shared/yaml-parser";
+import { mapToGemini } from "./shared/model-mapping";
+
+const PLUGIN_VERSION = "0.6.0";
+const SOURCE_DIR = join(import.meta.dir, "../plugins/lavra");
+const OUTPUT_DIR = join(import.meta.dir, "../plugins/lavra/gemini");
+
+/**
+ * Safely converts template syntax while preventing injection
+ * Escapes existing {{ }} syntax before adding new template variables
+ */
+function convertTemplateSyntax(content: string): string {
+  // First, escape any existing template syntax to prevent injection
+  let safe = content
+    .replace(/\{\{/g, "\\{\\{")
+    .replace(/\}\}/g, "\\}\\}");
+
+  // Then perform safe substitutions for known variables
+  // Only convert $ARGUMENTS if it's not inside a code block
+  const lines = safe.split("\n");
+  const converted: string[] = [];
+  let inCodeBlock = false;
+
+  for (const line of lines) {
+    // Track code blocks
+    if (line.trim().startsWith("```")) {
+      inCodeBlock = !inCodeBlock;
+      converted.push(line);
+      continue;
+    }
+
+    // Only convert outside code blocks
+    if (!inCodeBlock) {
+      converted.push(line.replace(/\$ARGUMENTS(?!\w)/g, "{{args}}"));
+    } else {
+      converted.push(line);
+    }
+  }
+
+  return converted.join("\n");
+}
+
+/**
+ * Generates TOML format for Gemini commands
+ */
+function generateTOML(description: string, prompt: string): string {
+  // Escape double quotes in strings
+  const escapedDesc = description.replace(/"/g, '\\"');
+  const escapedPrompt = prompt.replace(/"""/g, '\\"\\"\\"');
+
+  return `# Generated by lavra v${PLUGIN_VERSION}
+# DO NOT EDIT - changes will be overwritten on next install
+
+description = "${escapedDesc}"
+
+prompt = """
+${escapedPrompt}
+"""
+`;
+}
+
+/**
+ * Converts commands (.md → .toml with template syntax conversion)
+ */
+async function convertCommands() {
+  console.log("Converting commands...");
+
+  const commandsDir = validatePath(SOURCE_DIR, "commands");
+  const outputDir = validatePath(OUTPUT_DIR, "commands");
+
+  await mkdir(outputDir, { recursive: true, mode: 0o755 });
+
+  const files = await readdir(commandsDir);
+  const mdFiles = files.filter((f) => f.endsWith(".md"));
+
+  // Parallel processing for performance
+  await Promise.all(
+    mdFiles.map(async (file) => {
+      if (!validateFilename(file)) {
+        console.warn(`  ⚠️  Skipping invalid filename: ${file}`);
+        return;
+      }
+
+      const sourcePath = validatePath(commandsDir, file);
+      const baseName = file.replace(/\.md$/, "");
+      const outputPath = validatePath(
+        outputDir,
+        sanitizeFilename(baseName) + ".toml"
+      );
+
+      const content = await readFileSafe(sourcePath);
+      const frontmatter = parseFrontmatter(content);
+      const body = extractBody(content);
+
+      // Extract description from frontmatter
+      const description = frontmatter.description || baseName;
+
+      // Convert template syntax safely
+      const convertedPrompt = convertTemplateSyntax(body);
+
+      // Generate TOML
+      const toml = generateTOML(description, convertedPrompt);
+
+      await writeFileSafe(outputPath, toml, 0o644);
+      console.log(`  ✓ ${file} → ${baseName}.toml`);
+    })
+  );
+
+  console.log(`  Converted ${mdFiles.length} commands\n`);
+}
+
+/**
+ * Converts agents (field mapping required)
+ */
+async function convertAgents() {
+  console.log("Converting agents...");
+
+  const categories = ["review", "research", "design", "workflow", "docs"];
+  let totalConverted = 0;
+
+  // Create all category directories upfront
+  await Promise.all(
+    categories.map((category) =>
+      mkdir(join(OUTPUT_DIR, "agents", category), {
+        recursive: true,
+        mode: 0o755,
+      })
+    )
+  );
+
+  // Process each category in parallel
+  await Promise.all(
+    categories.map(async (category) => {
+      const categoryDir = validatePath(SOURCE_DIR, `agents/${category}`);
+      const outputCategoryDir = validatePath(OUTPUT_DIR, `agents/${category}`);
+
+      const files = await readdir(categoryDir);
+      const mdFiles = files.filter((f) => f.endsWith(".md"));
+
+      // Process files in parallel
+      await Promise.all(
+        mdFiles.map(async (file) => {
+          if (!validateFilename(file)) {
+            console.warn(`  ⚠️  Skipping invalid filename: ${file}`);
+            return;
+          }
+
+          const sourcePath = validatePath(categoryDir, file);
+          const outputPath = validatePath(outputCategoryDir, sanitizeFilename(file));
+
+          const content = await readFileSafe(sourcePath);
+          const frontmatter = parseFrontmatter(content);
+          const body = extractBody(content);
+
+          // Transform frontmatter for Gemini
+          const geminiFrontmatter: Record<string, any> = {
+            name: frontmatter.name || file.replace(/\.md$/, ""),
+            description: frontmatter.description || "",
+            kind: "local",
+          };
+
+          // Map model if present
+          if (frontmatter.model) {
+            const mappedModel = mapToGemini(frontmatter.model);
+            validateModelName(mappedModel);
+            geminiFrontmatter.model = mappedModel;
+          } else {
+            geminiFrontmatter.model = "gemini-2.5-pro";
+          }
+
+          // Add Gemini-specific fields
+          geminiFrontmatter.max_turns = 30;
+          geminiFrontmatter.timeout_mins = 10;
+
+          // Build output
+          const output = buildMarkdown(geminiFrontmatter, body);
+
+          // Add generation header
+          const withHeader = `<!-- Generated by lavra v${PLUGIN_VERSION} -->
+<!-- Source: ${category}/${file} -->
+<!-- DO NOT EDIT - changes will be overwritten on next install -->
+
+${output}`;
+
+          await writeFileSafe(outputPath, withHeader, 0o644);
+          console.log(`  ✓ ${category}/${file}`);
+        })
+      );
+
+      totalConverted += mdFiles.length;
+    })
+  );
+
+  console.log(`  Converted ${totalConverted} agents\n`);
+}
+
+/**
+ * Converts skills (direct copy - same format)
+ */
+async function convertSkills() {
+  console.log("Converting skills...");
+
+  const skillsDir = validatePath(SOURCE_DIR, "skills");
+  const outputDir = validatePath(OUTPUT_DIR, "skills");
+
+  await mkdir(outputDir, { recursive: true, mode: 0o755 });
+
+  const skillDirs = await readdir(skillsDir, { withFileTypes: true });
+  const skills = skillDirs.filter((d) => d.isDirectory() && d.name !== "optional").map((d) => d.name);
+
+  // Process each skill directory in parallel
+  await Promise.all(
+    skills.map(async (skill) => {
+      const skillDir = validatePath(skillsDir, skill);
+      const outputSkillDir = validatePath(outputDir, sanitizeFilename(skill));
+
+      await mkdir(outputSkillDir, { recursive: true, mode: 0o755 });
+
+      // Copy SKILL.md
+      const skillMd = join(skillDir, "SKILL.md");
+      const outputSkillMd = join(outputSkillDir, "SKILL.md");
+
+      try {
+        const content = await readFileSafe(skillMd);
+
+        // Add generation header
+        const withHeader = `<!-- Generated by lavra v${PLUGIN_VERSION} -->
+<!-- Source: ${skill}/SKILL.md -->
+<!-- DO NOT EDIT - changes will be overwritten on next install -->
+
+${content}`;
+
+        await writeFileSafe(outputSkillMd, withHeader, 0o644); // Standard permissions
+        console.log(`  ✓ ${skill}/SKILL.md`);
+      } catch (err) {
+        console.warn(`  ⚠️  Skipping ${skill} (no SKILL.md found): ${err}`);
+      }
+    })
+  );
+
+  console.log(`  Converted ${skills.length} skills\n`);
+}
+
+/**
+ * Generates documentation about MCP server configuration
+ */
+async function generateMCPDocs() {
+  console.log("Generating MCP configuration docs...");
+
+  const docsDir = validatePath(OUTPUT_DIR, "docs");
+  await mkdir(docsDir, { recursive: true, mode: 0o755 });
+
+  const mcpDocs = `# MCP Server Configuration for Gemini CLI
+
+The lavra plugin uses the Context7 MCP server for framework documentation.
+
+## Manual Configuration Required
+
+Gemini CLI does not support automatic MCP server installation. You need to manually add the server to your Gemini configuration.
+
+### Configuration File
+
+Add to \`~/.config/gemini/settings.json\`:
+
+\`\`\`json
+{
+  "mcpServers": {
+    "context7": {
+      "command": "npx",
+      "args": ["-y", "@upwithcrowd/context7-mcp@latest"],
+      "env": {}
+    }
+  }
+}
+\`\`\`
+
+### What Context7 Provides
+
+- Semantic search across PostgreSQL and TimescaleDB documentation
+- Framework-specific best practices and patterns
+- API reference lookups
+
+### Usage in Gemini CLI
+
+Once configured, use the \`@context7\` MCP tool to search documentation:
+
+\`\`\`
+@context7 search_docs source=postgres query="create hypertable" search_type=semantic
+\`\`\`
+
+## Security Note
+
+The Context7 MCP server runs as a subprocess with access to your environment. Only install if you trust the source.
+`;
+
+  const docsPath = join(docsDir, "MCP_SETUP.md");
+  await writeFileSafe(docsPath, mcpDocs, 0o644);
+
+  console.log(`  ✓ Generated MCP_SETUP.md\n`);
+}
+
+/**
+ * Main conversion function
+ */
+async function main() {
+  console.log("🔄 Converting lavra to Gemini CLI format\n");
+  console.log(`Source: ${SOURCE_DIR}`);
+  console.log(`Output: ${OUTPUT_DIR}\n`);
+
+  try {
+    // Create root output directory
+    await mkdir(OUTPUT_DIR, { recursive: true, mode: 0o755 });
+
+    // Run all conversions in parallel
+    await Promise.all([
+      convertCommands(),
+      convertAgents(),
+      convertSkills(),
+      generateMCPDocs(),
+    ]);
+
+    console.log("✅ Conversion complete!");
+    console.log(`\nGenerated files in: ${OUTPUT_DIR}`);
+    console.log("\nNext steps:");
+    console.log("1. Review the generated files");
+    console.log("2. Install as Gemini extension:");
+    console.log("   gemini extensions install https://github.com/roberto-mello/lavra");
+    console.log("3. Configure MCP servers (see gemini/docs/MCP_SETUP.md)");
+  } catch (err: any) {
+    console.error("❌ Conversion failed:", err.message);
+    process.exit(1);
+  }
+}
+
+// Run if executed directly
+if (import.meta.main) {
+  main();
+}
+
+export { convertCommands, convertAgents, convertSkills };

package/scripts/convert-opencode.ts

@@ -0,0 +1,313 @@
+#!/usr/bin/env bun
+
+/**
+ * convert-opencode.ts
+ * Converts lavra plugin files from Claude Code format to OpenCode format
+ *
+ * Security controls:
+ * - Path traversal protection
+ * - File size limits (10MB)
+ * - YAML SAFE_SCHEMA parsing
+ * - Model name validation
+ * - Explicit file permissions (644)
+ */
+
+import { readdir, mkdir } from "node:fs/promises";
+import { join, basename } from "node:path";
+import {
+  validatePath,
+  sanitizeFilename,
+  readFileSafe,
+  writeFileSafe,
+  validateModelName,
+  validateFilename,
+} from "./shared/security";
+import {
+  parseFrontmatter,
+  extractBody,
+  buildMarkdown,
+} from "./shared/yaml-parser";
+import { mapToOpenCode } from "./shared/model-mapping";
+
+const PLUGIN_VERSION = "0.6.0";
+const SOURCE_DIR = join(import.meta.dir, "../plugins/lavra");
+const OUTPUT_DIR = join(import.meta.dir, "../plugins/lavra/opencode");
+
+/**
+ * Converts commands (direct copy - formats are identical)
+ */
+async function convertCommands() {
+  console.log("Converting commands...");
+
+  const commandsDir = validatePath(SOURCE_DIR, "commands");
+  const outputDir = validatePath(OUTPUT_DIR, "commands");
+
+  await mkdir(outputDir, { recursive: true, mode: 0o755 });
+
+  const files = await readdir(commandsDir);
+  const mdFiles = files.filter((f) => f.endsWith(".md"));
+
+  // Parallel processing for performance
+  await Promise.all(
+    mdFiles.map(async (file) => {
+      if (!validateFilename(file)) {
+        console.warn(`  ⚠️  Skipping invalid filename: ${file}`);
+        return;
+      }
+
+      const sourcePath = validatePath(commandsDir, file);
+      const outputPath = validatePath(outputDir, sanitizeFilename(file));
+
+      const content = await readFileSafe(sourcePath);
+
+      // Add generation header
+      const withHeader = `<!-- Generated by lavra v${PLUGIN_VERSION} -->
+<!-- Source: ${file} -->
+<!-- DO NOT EDIT - changes will be overwritten on next install -->
+
+${content}`;
+
+      await writeFileSafe(outputPath, withHeader, 0o644);
+      console.log(`  ✓ ${file}`);
+    })
+  );
+
+  console.log(`  Converted ${mdFiles.length} commands\n`);
+}
+
+/**
+ * Converts agents (field mapping required)
+ */
+async function convertAgents() {
+  console.log("Converting agents...");
+
+  const categories = ["review", "research", "design", "workflow", "docs"];
+  let totalConverted = 0;
+
+  // Create all category directories upfront
+  await Promise.all(
+    categories.map((category) =>
+      mkdir(join(OUTPUT_DIR, "agents", category), {
+        recursive: true,
+        mode: 0o755,
+      })
+    )
+  );
+
+  // Process each category in parallel
+  await Promise.all(
+    categories.map(async (category) => {
+      const categoryDir = validatePath(SOURCE_DIR, `agents/${category}`);
+      const outputCategoryDir = validatePath(OUTPUT_DIR, `agents/${category}`);
+
+      const files = await readdir(categoryDir);
+      const mdFiles = files.filter((f) => f.endsWith(".md"));
+
+      // Process files in parallel
+      await Promise.all(
+        mdFiles.map(async (file) => {
+          if (!validateFilename(file)) {
+            console.warn(`  ⚠️  Skipping invalid filename: ${file}`);
+            return;
+          }
+
+          const sourcePath = validatePath(categoryDir, file);
+          const outputPath = validatePath(outputCategoryDir, sanitizeFilename(file));
+
+          const content = await readFileSafe(sourcePath);
+          const frontmatter = parseFrontmatter(content);
+          const body = extractBody(content);
+
+          // Transform frontmatter for OpenCode
+          const opencodeFrontmatter: Record<string, any> = {
+            description: frontmatter.description || "",
+            mode: "subagent",
+          };
+
+          // Map model if present and not inherit
+          if (frontmatter.model && frontmatter.model !== "inherit") {
+            const mappedModel = mapToOpenCode(frontmatter.model);
+            validateModelName(mappedModel);
+            opencodeFrontmatter.model = mappedModel;
+          } else {
+            opencodeFrontmatter.model = "inherit";
+          }
+
+          // Build output
+          const output = buildMarkdown(opencodeFrontmatter, body);
+
+          // Add generation header
+          const withHeader = `<!-- Generated by lavra v${PLUGIN_VERSION} -->
+<!-- Source: ${category}/${file} -->
+<!-- DO NOT EDIT - changes will be overwritten on next install -->
+
+${output}`;
+
+          await writeFileSafe(outputPath, withHeader, 0o644);
+          console.log(`  ✓ ${category}/${file}`);
+        })
+      );
+
+      totalConverted += mdFiles.length;
+    })
+  );
+
+  console.log(`  Converted ${totalConverted} agents\n`);
+}
+
+/**
+ * Converts skills (direct copy - OpenCode searches .claude/skills/ automatically)
+ * We still copy them for completeness and to allow .opencode/ to be standalone
+ */
+async function convertSkills() {
+  console.log("Converting skills...");
+
+  const skillsDir = validatePath(SOURCE_DIR, "skills");
+  const outputDir = validatePath(OUTPUT_DIR, "skills");
+
+  await mkdir(outputDir, { recursive: true, mode: 0o755 });
+
+  const skillDirs = await readdir(skillsDir, { withFileTypes: true });
+  const skills = skillDirs.filter((d) => d.isDirectory() && d.name !== "optional").map((d) => d.name);
+
+  // Process each skill directory in parallel
+  await Promise.all(
+    skills.map(async (skill) => {
+      const skillDir = validatePath(skillsDir, skill);
+      const outputSkillDir = validatePath(outputDir, sanitizeFilename(skill));
+
+      await mkdir(outputSkillDir, { recursive: true, mode: 0o755 });
+
+      // Copy SKILL.md
+      const skillMd = join(skillDir, "SKILL.md");
+      const outputSkillMd = join(outputSkillDir, "SKILL.md");
+
+      try {
+        const content = await readFileSafe(skillMd);
+
+        // Add generation header
+        const withHeader = `<!-- Generated by lavra v${PLUGIN_VERSION} -->
+<!-- Source: ${skill}/SKILL.md -->
+<!-- DO NOT EDIT - changes will be overwritten on next install -->
+
+${content}`;
+
+        await writeFileSafe(outputSkillMd, withHeader, 0o644); // Standard permissions
+        console.log(`  ✓ ${skill}/SKILL.md`);
+      } catch (err) {
+        console.warn(`  ⚠️  Skipping ${skill} (no SKILL.md found): ${err}`);
+      }
+    })
+  );
+
+  console.log(`  Converted ${skills.length} skills\n`);
+}
+
+/**
+ * Generates documentation about MCP server configuration
+ */
+async function generateMCPDocs() {
+  console.log("Generating MCP configuration docs...");
+
+  const docsDir = validatePath(OUTPUT_DIR, "docs");
+  await mkdir(docsDir, { recursive: true, mode: 0o755 });
+
+  const mcpDocs = `# MCP Server Configuration for OpenCode
+
+The lavra plugin uses the Context7 MCP server for framework documentation.
+
+## Manual Configuration Required
+
+OpenCode does not support automatic MCP server installation. You need to manually add the server to your OpenCode configuration.
+
+### Configuration File
+
+Add to \`~/.config/opencode/config.json\` or your project's \`opencode.json\`:
+
+\`\`\`json
+{
+  "mcpServers": {
+    "context7": {
+      "command": "npx",
+      "args": ["-y", "@upwithcrowd/context7-mcp@latest"],
+      "env": {}
+    }
+  }
+}
+\`\`\`
+
+### What Context7 Provides
+
+- Semantic search across PostgreSQL and TimescaleDB documentation
+- Framework-specific best practices and patterns
+- API reference lookups
+
+### Usage in OpenCode
+
+Once configured, agents can use the Context7 tools to search documentation:
+
+\`\`\`typescript
+// Example: Search PostgreSQL docs
+await mcp.call("context7", "search_docs", {
+  source: "postgres",
+  search_type: "semantic",
+  query: "create hypertable with compression",
+  version: "latest",
+  limit: 5
+});
+\`\`\`
+
+## Security Note
+
+The Context7 MCP server runs as a subprocess with access to your environment. Only install if you trust the source.
+`;
+
+  const docsPath = join(docsDir, "MCP_SETUP.md");
+  await writeFileSafe(docsPath, mcpDocs, 0o644);
+
+  console.log(`  ✓ Generated MCP_SETUP.md\n`);
+}
+
+/**
+ * Main conversion function
+ */
+async function main() {
+  console.log("🔄 Converting lavra to OpenCode format\n");
+  console.log(`Source: ${SOURCE_DIR}`);
+  console.log(`Output: ${OUTPUT_DIR}\n`);
+
+  try {
+    // Create root output directory
+    await mkdir(OUTPUT_DIR, { recursive: true, mode: 0o755 });
+
+    // Run all conversions in parallel
+    await Promise.all([
+      convertCommands(),
+      convertAgents(),
+      convertSkills(),
+      generateMCPDocs(),
+    ]);
+
+    console.log("✅ Conversion complete!");
+    console.log(`\nGenerated files in: ${OUTPUT_DIR}`);
+
+    // Only show manual copy instructions if running standalone (not during install)
+    if (!process.env.LAVRA_INSTALLING) {
+      console.log("\nNext steps:");
+      console.log("1. Review the generated files");
+      console.log("2. Copy to your OpenCode project:");
+      console.log(`   cp -r ${OUTPUT_DIR}/* <project>/.opencode/`);
+      console.log("3. Configure MCP servers (see opencode/docs/MCP_SETUP.md)");
+    }
+  } catch (err: any) {
+    console.error("❌ Conversion failed:", err.message);
+    process.exit(1);
+  }
+}
+
+// Run if executed directly
+if (import.meta.main) {
+  main();
+}
+
+export { convertCommands, convertAgents, convertSkills };

package/scripts/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "lavra-converters",
+  "version": "0.6.0",
+  "description": "Conversion scripts for lavra multi-platform support",
+  "type": "module",
+  "scripts": {
+    "convert:opencode": "bun run convert-opencode.ts",
+    "convert:gemini": "bun run convert-gemini.ts",
+    "convert:all": "bun run convert-opencode.ts && bun run convert-gemini.ts",
+    "test:security": "bun run test-security.ts",
+    "test:compatibility": "bun run test-compatibility.ts",
+    "test:all": "bun run test-security.ts && bun run test-compatibility.ts"
+  },
+  "dependencies": {
+    "js-yaml": "4.1.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/js-yaml": "4.0.9"
+  },
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "overrides": {
+    "js-yaml": "4.1.0"
+  }
+}