@cyber-dash-tech/revela 0.1.0

package/tools/designs.ts

@@ -0,0 +1,126 @@
+import { tool } from "@opencode-ai/plugin"
+import {
+  listDesigns,
+  activeDesign,
+  activateDesign,
+  installDesign,
+  removeDesign,
+  parseDesignSections,
+  generateComponentIndex,
+  getDesignSection,
+  getDesignComponent,
+} from "../lib/design/designs"
+import { buildPrompt } from "../lib/prompt-builder"
+import { existsSync, readFileSync } from "fs"
+import { join } from "path"
+import { DESIGNS_DIR } from "../lib/config"
+import { parseFrontmatter } from "../lib/frontmatter"
+
+export default tool({
+  description:
+    "Manage revela visual design templates. " +
+    "Use action 'list' to show all installed designs with names and descriptions. " +
+    "Use action 'activate' to switch to a different design (requires name). " +
+    "Use action 'install' to add a new design from a URL, local path, or github:user/repo shorthand (requires source). " +
+    "Use action 'remove' to uninstall a design (requires name). " +
+    "Use action 'read' to fetch on-demand design content: pass component (comma-separated names) to get full CSS/HTML for specific components, or section ('charts' | 'guide' | 'global' | 'layouts' | 'components') to get an entire section. Pass neither to get the Component Index table. " +
+    "After activating a new design, the system prompt is automatically rebuilt.",
+  args: {
+    action: tool.schema
+      .enum(["list", "activate", "install", "remove", "read"])
+      .describe("Operation to perform"),
+    name: tool.schema
+      .string()
+      .optional()
+      .describe("Design name — required for activate and remove; optional for read (defaults to active design)"),
+    source: tool.schema
+      .string()
+      .optional()
+      .describe(
+        "Install source — URL, local path, github:user/repo. Required for install."
+      ),
+    component: tool.schema
+      .string()
+      .optional()
+      .describe(
+        "For action 'read': comma-separated component name(s) to fetch (e.g. 'card', 'card,stat-card')"
+      ),
+    section: tool.schema
+      .string()
+      .optional()
+      .describe(
+        "For action 'read': section name to fetch — 'charts', 'guide', 'global', 'layouts', or 'components'"
+      ),
+  },
+  async execute(args) {
+    try {
+      switch (args.action) {
+        case "list": {
+          const designs = listDesigns()
+          const current = activeDesign()
+          return JSON.stringify(
+            designs.map((d) => ({
+              name: d.name,
+              description: d.description,
+              author: d.author,
+              version: d.version,
+              active: d.name === current,
+            })),
+            null,
+            2,
+          )
+        }
+        case "activate": {
+          if (!args.name) return JSON.stringify({ error: "name is required for activate" })
+          activateDesign(args.name)
+          buildPrompt()
+          return JSON.stringify({ ok: true })
+        }
+        case "install": {
+          if (!args.source) return JSON.stringify({ error: "source is required for install" })
+          const installed = await installDesign(args.source, args.name)
+          return JSON.stringify({ ok: true, name: installed })
+        }
+        case "remove": {
+          if (!args.name) return JSON.stringify({ error: "name is required for remove" })
+          removeDesign(args.name)
+          return JSON.stringify({ ok: true })
+        }
+        case "read": {
+          const designName = args.name || activeDesign()
+
+          // Read raw body to check for markers
+          const mdPath = join(DESIGNS_DIR, designName, "DESIGN.md")
+          if (!existsSync(mdPath)) {
+            return JSON.stringify({ error: `Design '${designName}' is not installed` })
+          }
+          const raw = readFileSync(mdPath, "utf-8")
+          const { body } = parseFrontmatter(raw)
+          const { components, hasMarkers } = parseDesignSections(body)
+
+          if (!hasMarkers) {
+            // No markers — return full body
+            return body
+          }
+
+          // Specific component(s) requested
+          if (args.component) {
+            return getDesignComponent(args.component, designName)
+          }
+
+          // Specific section requested
+          if (args.section) {
+            return getDesignSection(args.section, designName)
+          }
+
+          // Default: return Component Index
+          return generateComponentIndex(components)
+        }
+        default:
+          return JSON.stringify({ error: `Unknown action: ${args.action}` })
+      }
+    } catch (e: any) {
+      return JSON.stringify({ error: e.message || String(e) })
+    }
+  },
+})

package/tools/domains.ts

@@ -0,0 +1,73 @@
+import { tool } from "@opencode-ai/plugin"
+import {
+  listDomains,
+  activeDomain,
+  activateDomain,
+  installDomain,
+  removeDomain,
+} from "../lib/domain/domains"
+import { buildPrompt } from "../lib/prompt-builder"
+
+export default tool({
+  description:
+    "Manage revela domain definitions (industry/topic specializations). " +
+    "Use action 'list' to show all installed domains with names and descriptions. " +
+    "Use action 'activate' to switch to a different domain (requires name). " +
+    "Use action 'install' to add a new domain from a URL, local path, or github:user/repo shorthand (requires source). " +
+    "Use action 'remove' to uninstall a domain — 'general' cannot be removed (requires name). " +
+    "After activating a new domain, the system prompt is automatically rebuilt.",
+  args: {
+    action: tool.schema
+      .enum(["list", "activate", "install", "remove"])
+      .describe("Operation to perform"),
+    name: tool.schema
+      .string()
+      .optional()
+      .describe("Domain name — required for activate and remove"),
+    source: tool.schema
+      .string()
+      .optional()
+      .describe("Install source — URL, local path, github:user/repo. Required for install."),
+  },
+  async execute(args) {
+    try {
+      switch (args.action) {
+        case "list": {
+          const domains = listDomains()
+          const current = activeDomain()
+          return JSON.stringify(
+            domains.map((d) => ({
+              name: d.name,
+              description: d.description,
+              author: d.author,
+              version: d.version,
+              active: d.name === current,
+            })),
+            null,
+            2,
+          )
+        }
+        case "activate": {
+          if (!args.name) return JSON.stringify({ error: "name is required for activate" })
+          activateDomain(args.name)
+          buildPrompt()
+          return JSON.stringify({ ok: true })
+        }
+        case "install": {
+          if (!args.source) return JSON.stringify({ error: "source is required for install" })
+          const installed = await installDomain(args.source, args.name)
+          return JSON.stringify({ ok: true, name: installed })
+        }
+        case "remove": {
+          if (!args.name) return JSON.stringify({ error: "name is required for remove" })
+          removeDomain(args.name)
+          return JSON.stringify({ ok: true })
+        }
+        default:
+          return JSON.stringify({ error: `Unknown action: ${args.action}` })
+      }
+    } catch (e: any) {
+      return JSON.stringify({ error: e.message || String(e) })
+    }
+  },
+})

package/tools/qa.ts

@@ -0,0 +1,61 @@
+/**
+ * tools/qa.ts
+ *
+ * revela-qa — Layout quality assurance tool for generated slide HTML files.
+ *
+ * Exposed to the LLM so it can run layout checks after writing a slides file.
+ * Also called automatically by the tool.execute.after hook in plugin.ts
+ * when the LLM writes a file matching slides/*.html.
+ */
+
+import { tool } from "@opencode-ai/plugin"
+import { resolve } from "path"
+import { existsSync } from "fs"
+import { runQA, formatReport } from "../lib/qa"
+
+export default tool({
+  description:
+    "Run layout quality checks on a generated slide HTML file. " +
+    "Opens the file in a headless browser and measures actual rendered geometry. " +
+    "Checks for: canvas underfill (too much empty space), bottom whitespace, " +
+    "left-right column asymmetry, element overflow, and card height variance. " +
+    "Returns a structured report with specific issues and fix instructions. " +
+    "Call this after writing or editing any slides/*.html file to verify layout quality.",
+  args: {
+    file: tool.schema
+      .string()
+      .describe(
+        "Path to the HTML slide file to check. " +
+        "Can be absolute or relative to the current working directory."
+      ),
+  },
+  async execute({ file }, { directory }) {
+    // Resolve path relative to working directory
+    const filePath = resolve(directory || process.cwd(), file)
+
+    if (!existsSync(filePath)) {
+      return `Error: File not found: ${filePath}`
+    }
+
+    if (!filePath.endsWith(".html")) {
+      return `Error: File must be an HTML file: ${filePath}`
+    }
+
+    try {
+      const report = await runQA(filePath)
+      const formatted = formatReport(report)
+
+      // Prepend a compact JSON summary for programmatic use if needed
+      const jsonSummary = JSON.stringify({
+        totalIssues: report.totalIssues,
+        errors: report.errorCount,
+        warnings: report.warningCount,
+        slidesWithIssues: report.slides.filter((s) => s.issues.length > 0).map((s) => s.index + 1),
+      })
+
+      return `<!-- QA Summary: ${jsonSummary} -->\n\n${formatted}`
+    } catch (err: any) {
+      return `Error running layout QA: ${err?.message ?? String(err)}\n\nMake sure Chrome is installed at /Applications/Google Chrome.app`
+    }
+  },
+})

package/tools/research-save.ts

@@ -0,0 +1,96 @@
+import { tool } from "@opencode-ai/plugin"
+import { mkdirSync, writeFileSync } from "fs"
+import { join } from "path"
+
+/**
+ * Format today's date as YYYY-MM-DD
+ */
+function today(): string {
+  return new Date().toISOString().slice(0, 10)
+}
+
+/**
+ * Sanitize a slug: lowercase, alphanumeric + hyphens only.
+ */
+function slugify(s: string): string {
+  return s
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+}
+
+/**
+ * Build YAML frontmatter string.
+ */
+function buildFrontmatter(topic: string, axis: string, sources: string[]): string {
+  const lines = [
+    "---",
+    `topic: ${topic}`,
+    `axis: ${axis}`,
+    `date: ${today()}`,
+  ]
+  if (sources.length > 0) {
+    lines.push("sources:")
+    for (const s of sources) {
+      lines.push(`  - "${s.replace(/"/g, '\\"')}"`)
+    }
+  }
+  lines.push("---")
+  return lines.join("\n")
+}
+
+export default tool({
+  description:
+    "Save a research findings file to the workspace researches/ directory. " +
+    "Creates researches/{topic}/{filename}.md with YAML frontmatter. " +
+    "Each research axis gets its own file (e.g. 'market-data', 'catl-profile'). " +
+    "Content should use ## Data / ## Cases / ## Images / ## Gaps sections.",
+  args: {
+    topic: tool.schema
+      .string()
+      .describe(
+        "Topic slug in kebab-case, e.g. 'ev-battery-market' or 'saas-competitive-analysis'. " +
+        "All files for the same presentation share the same topic slug.",
+      ),
+    filename: tool.schema
+      .string()
+      .describe(
+        "Axis name without extension, e.g. 'market-data', 'catl-profile', 'tech-trends'. " +
+        "Each parallel research agent uses a unique axis name.",
+      ),
+    content: tool.schema
+      .string()
+      .describe(
+        "Structured markdown findings. Use these sections (omit empty ones):\n" +
+        "## Data — key stats and data points, each with [Source: url]\n" +
+        "## Cases — company/entity profiles, 1-2 sentences each with [Source: url]\n" +
+        "## Images — image URLs: '{description}: {url} | Alt: {text} | Use: logo|screenshot|portrait'\n" +
+        "## Gaps — topics not found or insufficiently covered",
+      ),
+    sources: tool.schema
+      .array(tool.schema.string())
+      .optional()
+      .describe("Source URLs or filenames for YAML frontmatter, e.g. ['https://example.com/report', 'data.xlsx']"),
+  },
+  async execute(args, context) {
+    try {
+      const topicSlug = slugify(args.topic || "research")
+      const fileSlug = slugify(args.filename || "findings")
+      const workspaceDir = context.directory ?? process.cwd()
+      const topicDir = join(workspaceDir, "researches", topicSlug)
+
+      mkdirSync(topicDir, { recursive: true })
+
+      const frontmatter = buildFrontmatter(args.topic, fileSlug, args.sources ?? [])
+      const fileContent = `${frontmatter}\n\n${args.content ?? ""}\n`
+      const filePath = join(topicDir, `${fileSlug}.md`)
+      const relPath = `researches/${topicSlug}/${fileSlug}.md`
+
+      writeFileSync(filePath, fileContent, "utf-8")
+
+      return JSON.stringify({ ok: true, path: relPath })
+    } catch (e: any) {
+      return JSON.stringify({ error: e.message || String(e) })
+    }
+  },
+})

package/tools/workspace-scan.ts

@@ -0,0 +1,154 @@
+import { tool } from "@opencode-ai/plugin"
+import { readdirSync, statSync, existsSync } from "fs"
+import { join, relative, extname } from "path"
+
+const DOC_EXTENSIONS = new Set([
+  ".pdf", ".docx", ".doc", ".xlsx", ".xls",
+  ".pptx", ".ppt", ".csv", ".md", ".txt",
+])
+
+// Directories to exclude from scanning
+const EXCLUDE_DIRS = new Set([
+  "node_modules", ".git", "dist", ".opencode",
+  "researches",  // Exclude revela's own research output
+  "designs", "domains",  // Exclude revela plugin assets
+])
+
+type FileEntry = {
+  path: string
+  type: string
+  size: string
+}
+
+/**
+ * Format bytes into a human-readable size string.
+ */
+function formatSize(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`
+}
+
+/**
+ * Map extension to a friendly type label.
+ */
+function typeLabel(ext: string): string {
+  const map: Record<string, string> = {
+    ".pdf": "PDF",
+    ".docx": "Word",
+    ".doc": "Word",
+    ".xlsx": "Excel",
+    ".xls": "Excel",
+    ".pptx": "PowerPoint",
+    ".ppt": "PowerPoint",
+    ".csv": "CSV",
+    ".md": "Markdown",
+    ".txt": "Text",
+  }
+  return map[ext] ?? ext.slice(1).toUpperCase()
+}
+
+/**
+ * Recursively scan a directory for document files.
+ */
+function scanDir(dir: string, rootDir: string, results: FileEntry[], maxDepth: number, depth: number): void {
+  if (depth > maxDepth) return
+  if (!existsSync(dir)) return
+
+  let entries: string[]
+  try {
+    entries = readdirSync(dir)
+  } catch {
+    return
+  }
+
+  for (const entry of entries) {
+    // Skip hidden files/dirs and excluded dirs
+    if (entry.startsWith(".")) continue
+    if (EXCLUDE_DIRS.has(entry)) continue
+
+    const fullPath = join(dir, entry)
+    let stat
+    try {
+      stat = statSync(fullPath)
+    } catch {
+      continue
+    }
+
+    if (stat.isDirectory()) {
+      scanDir(fullPath, rootDir, results, maxDepth, depth + 1)
+    } else if (stat.isFile()) {
+      const ext = extname(entry).toLowerCase()
+      if (DOC_EXTENSIONS.has(ext)) {
+        results.push({
+          path: relative(rootDir, fullPath),
+          type: typeLabel(ext),
+          size: formatSize(stat.size),
+        })
+      }
+    }
+  }
+}
+
+export default tool({
+  description:
+    "Scan the current workspace for document and data files that can be used as research input. " +
+    "Returns a structured list of all found files with their type and size. " +
+    "Searches for: PDF, Word (docx/doc), Excel (xlsx/xls), PowerPoint (pptx/ppt), CSV, Markdown, and text files. " +
+    "Excludes node_modules, .git, dist, and the researches/ output directory. " +
+    "Use this as the first step before reading workspace documents.",
+  args: {
+    path: tool.schema
+      .string()
+      .optional()
+      .describe(
+        "Optional subdirectory to scan (relative to workspace root). " +
+        "If omitted, scans the entire workspace.",
+      ),
+    max_depth: tool.schema
+      .number()
+      .optional()
+      .describe("Maximum directory depth to recurse. Defaults to 6."),
+  },
+  async execute(args, context) {
+    try {
+      const workspaceDir = context.directory ?? process.cwd()
+      const scanRoot = args.path ? join(workspaceDir, args.path) : workspaceDir
+      const maxDepth = args.max_depth ?? 6
+
+      if (!existsSync(scanRoot)) {
+        return JSON.stringify({ error: `Path not found: ${args.path}` })
+      }
+
+      const results: FileEntry[] = []
+      scanDir(scanRoot, workspaceDir, results, maxDepth, 0)
+
+      if (results.length === 0) {
+        return JSON.stringify({
+          found: 0,
+          message: "No document files found in workspace.",
+          files: [],
+        })
+      }
+
+      // Sort by type then path for readability
+      results.sort((a, b) => a.type.localeCompare(b.type) || a.path.localeCompare(b.path))
+
+      // Build markdown table
+      const tableRows = results.map((f) => `| ${f.path} | ${f.type} | ${f.size} |`)
+      const table = [
+        "| File | Type | Size |",
+        "|------|------|------|",
+        ...tableRows,
+      ].join("\n")
+
+      return JSON.stringify({
+        found: results.length,
+        table,
+        files: results,
+      })
+    } catch (e: any) {
+      return JSON.stringify({ error: e.message || String(e) })
+    }
+  },
+})