@cyber-dash-tech/revela 0.1.0

package/lib/commands/enable.ts

@@ -0,0 +1,48 @@
+/**
+ * lib/commands/enable.ts
+ *
+ * Handler for `/revela enable` — activates slide generation mode.
+ */
+
+import { existsSync } from "fs"
+import { activeDesign } from "../design/designs"
+import { activeDomain } from "../domain/domains"
+import { ctx } from "../ctx"
+import { ACTIVE_PROMPT_FILE } from "../config"
+import { buildPrompt } from "../prompt-builder"
+import { log } from "../log"
+
+export async function handleEnable(
+  send: (text: string) => Promise<void>,
+): Promise<void> {
+  ctx.enabled = true
+  const design = activeDesign()
+  const domain = activeDomain()
+
+  // Health check: ensure the active prompt file exists.
+  // If startup failed (e.g. SKILL.md missing), rebuild now so the user gets a working session.
+  if (!existsSync(ACTIVE_PROMPT_FILE)) {
+    log.warn("active prompt file missing on enable — rebuilding", { promptFile: ACTIVE_PROMPT_FILE })
+    try {
+      buildPrompt()
+      log.info("prompt rebuilt on enable", { design, domain, promptFile: ACTIVE_PROMPT_FILE })
+    } catch (e) {
+      log.error("prompt rebuild failed on enable", { error: e instanceof Error ? e.message : String(e) })
+      await send(
+        `**Revela enabled (with warnings).** Slide generation mode is active, ` +
+        `but the prompt file could not be built. ` +
+        `Try \`/revela disable\` then \`/revela enable\` again, or check that the package is correctly installed.\n\n` +
+        `Design: \`${design}\` · Domain: \`${domain}\``
+      )
+      return
+    }
+  }
+
+  log.info("revela enabled", { design, domain })
+  await send(
+    `**Revela enabled.** Slide generation mode is now active.\n` +
+    `Design: \`${design}\` · Domain: \`${domain}\`\n\n` +
+    `The three-layer slide generation prompt will be injected into every message. ` +
+    `Describe your presentation to get started.`
+  )
+}

package/lib/commands/help.ts

@@ -0,0 +1,35 @@
+/**
+ * lib/commands/help.ts
+ *
+ * Handler for `/revela` (no sub-command) — shows status and command reference.
+ */
+
+import { activeDesign } from "../design/designs"
+import { activeDomain } from "../domain/domains"
+import { ctx } from "../ctx"
+
+export async function handleHelp(
+  send: (text: string) => Promise<void>,
+): Promise<void> {
+  const design = activeDesign()
+  const domain = activeDomain()
+  const status = ctx.enabled ? "enabled ✓" : "disabled"
+  await send(
+    `\`\`\`\n` +
+    `             R E V E L A\n` +
+    `\`\`\`\n` +
+    `**Status:** ${status}\n` +
+    `🟠 **Design:** \`${design}\`\n` +
+    `🟠 **Domain:** \`${domain}\`\n\n` +
+    `---\n\n` +
+    `**Commands**\n\n` +
+    `\`/revela enable\`              — enable slide generation mode\n` +
+    `\`/revela disable\`             — disable slide generation mode\n` +
+    `\`/revela designs\`             — list installed designs\n` +
+    `\`/revela designs <name>\`      — activate a design\n` +
+    `\`/revela domains\`             — list installed domains\n` +
+    `\`/revela domains <name>\`      — activate a domain\n` +
+    `\`/revela designs-add <url>\`   — install a design from URL / github:user/repo\n` +
+    `\`/revela domains-add <url>\`   — install a domain from URL / github:user/repo`
+  )
+}

package/lib/config.ts

@@ -0,0 +1,65 @@
+/**
+ * Config file management for revela.
+ *
+ * Reads/writes `~/.config/revela/config.json`.
+ * All paths are derived from CONFIG_DIR.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs"
+import { homedir } from "os"
+import { join } from "path"
+import { childLog } from "./log"
+
+const configLog = childLog("config")
+
+/** Root config directory for revela runtime data. */
+export const CONFIG_DIR = join(homedir(), ".config", "revela")
+
+/** Directory where installed designs are stored at runtime. */
+export const DESIGNS_DIR = join(CONFIG_DIR, "designs")
+
+/** Directory where installed domains are stored at runtime. */
+export const DOMAINS_DIR = join(CONFIG_DIR, "domains")
+
+/** Path to the main config file. */
+export const CONFIG_FILE = join(CONFIG_DIR, "config.json")
+
+/** Path to the dynamically generated system prompt. */
+export const ACTIVE_PROMPT_FILE = join(CONFIG_DIR, "_active-prompt.md")
+
+/** Default design name. */
+export const DEFAULT_DESIGN = "default"
+
+/** Default domain name. */
+export const DEFAULT_DOMAIN = "general"
+
+export interface SlidesConfig {
+  activeDesign?: string
+  activeDomain?: string
+  /** Legacy key — fallback for activeDesign. */
+  activeTemplate?: string
+  /** Legacy key — fallback for activeDomain. */
+  activeIndustry?: string
+  [key: string]: string | undefined
+}
+
+/** Load config.json, returning empty object on any error. */
+export function loadConfig(): SlidesConfig {
+  try {
+    if (existsSync(CONFIG_FILE)) {
+      return JSON.parse(readFileSync(CONFIG_FILE, "utf-8"))
+    }
+  } catch (e) {
+    configLog.warn("config.json is corrupt or unreadable — using defaults", {
+      configFile: CONFIG_FILE,
+      error: e instanceof Error ? e.message : String(e),
+    })
+  }
+  return {}
+}
+
+/** Write config.json atomically. Creates parent dirs if needed. */
+export function saveConfig(config: SlidesConfig): void {
+  mkdirSync(CONFIG_DIR, { recursive: true })
+  writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2), "utf-8")
+}

package/lib/ctx.ts

@@ -0,0 +1,27 @@
+/**
+ * lib/ctx.ts — Revela Global Runtime Context
+ *
+ * A session-level singleton shared across all modules: plugin hooks,
+ * read-hooks, future subagents, and any other feature modules.
+ *
+ * Lifecycle: resets on OpenCode restart. NOT persisted to config.json.
+ * For persistent user preferences (activeDesign, activeDomain), see lib/config.ts.
+ */
+
+export interface RevelaCtx {
+  /** Master switch — controls prompt injection, read hooks, subagents, etc. */
+  enabled: boolean
+
+  /**
+   * True when the current LLM request originates from the revela-research subagent.
+   * Set in experimental.chat.system.transform by detecting RESEARCH_AGENT_SIGNATURE.
+   * Used by tool.execute.before to allow websearch for research agents only.
+   */
+  isResearchAgent: boolean
+}
+
+/** Global singleton. Import and use directly from any module. */
+export const ctx: RevelaCtx = {
+  enabled: false,
+  isResearchAgent: false,
+}

package/lib/design/designs.ts

@@ -0,0 +1,389 @@
+/**
+ * DesignManager — manage revela visual design templates.
+ *
+ * Designs are stored in ~/.config/revela/designs/<name>/.
+ * Each design directory contains DESIGN.md (required) and optionally preview.html.
+ *
+ * Built-in designs are shipped with the npm package under designs/ and seeded
+ * to the config directory on first run.
+ */
+
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from "fs"
+import { join, resolve, basename } from "path"
+import { tmpdir } from "os"
+import { parseFrontmatter } from "../frontmatter"
+import {
+  DESIGNS_DIR,
+  DEFAULT_DESIGN,
+  loadConfig,
+  saveConfig,
+} from "../config"
+import { childLog } from "../log"
+
+const designLog = childLog("designs")
+
+// Seed directory: built-in designs shipped with this package.
+const SEED_DIR = resolve(__dirname, "../..", "designs")
+
+export interface DesignInfo {
+  name: string
+  description: string
+  author: string
+  version: string
+  skillText: string
+}
+
+// ---------------------------------------------------------------------------
+// Seed
+// ---------------------------------------------------------------------------
+
+/**
+ * Copy built-in designs from the package to ~/.config/revela/designs/.
+ * Always overwrites to keep bundled designs up to date.
+ * User-created designs (not in the seed directory) are never touched.
+ */
+export function seedBuiltinDesigns(): void {
+  if (!existsSync(SEED_DIR)) return
+  mkdirSync(DESIGNS_DIR, { recursive: true })
+
+  for (const entry of readdirSync(SEED_DIR)) {
+    const src = join(SEED_DIR, entry)
+    if (!statSync(src).isDirectory()) continue
+    if (!existsSync(join(src, "DESIGN.md"))) continue
+
+    const dst = join(DESIGNS_DIR, entry)
+    mkdirSync(dst, { recursive: true })
+    cpSync(src, dst, { recursive: true, force: true })
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Parse
+// ---------------------------------------------------------------------------
+
+/** Parse a DESIGN.md file into DesignInfo. Returns null on any error. */
+export function parseDesignFile(filePath: string): DesignInfo | null {
+  try {
+    const text = readFileSync(filePath, "utf-8")
+    const { meta, body } = parseFrontmatter(text)
+    return {
+      name: meta.name || basename(join(filePath, "..")),
+      description: meta.description || "",
+      author: meta.author || "unknown",
+      version: meta.version || "0.0.0",
+      skillText: body,
+    }
+  } catch (e) {
+    designLog.warn("failed to parse design file — skipping", {
+      filePath,
+      error: e instanceof Error ? e.message : String(e),
+    })
+    return null
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/** List all installed designs, sorted by name. */
+export function listDesigns(): DesignInfo[] {
+  if (!existsSync(DESIGNS_DIR)) return []
+  const results: DesignInfo[] = []
+
+  for (const entry of readdirSync(DESIGNS_DIR).sort()) {
+    const dir = join(DESIGNS_DIR, entry)
+    if (!statSync(dir).isDirectory()) continue
+    const mdPath = join(dir, "DESIGN.md")
+    if (!existsSync(mdPath)) continue
+    const info = parseDesignFile(mdPath)
+    if (info) results.push(info)
+  }
+  return results
+}
+
+/** Get the name of the currently active design. */
+export function activeDesign(): string {
+  const cfg = loadConfig()
+  return cfg.activeDesign || cfg.activeTemplate || DEFAULT_DESIGN
+}
+
+/** Set the active design. Throws if design is not installed. */
+export function activateDesign(name: string): void {
+  if (!designExists(name)) {
+    throw new Error(`Design '${name}' is not installed`)
+  }
+  const cfg = loadConfig()
+  cfg.activeDesign = name
+  saveConfig(cfg)
+}
+
+/** Get the skill text body from a design's DESIGN.md. */
+export function getDesignSkillMd(name?: string): string {
+  const designName = name || activeDesign()
+  const mdPath = join(DESIGNS_DIR, designName, "DESIGN.md")
+  if (!existsSync(mdPath)) {
+    throw new Error(`Design '${designName}' is not installed`)
+  }
+  const info = parseDesignFile(mdPath)
+  if (!info) {
+    throw new Error(`Failed to parse DESIGN.md for '${designName}'`)
+  }
+  return info.skillText
+}
+
+// ---------------------------------------------------------------------------
+// Marker-based section / component parsing
+// ---------------------------------------------------------------------------
+
+export interface DesignSections {
+  /** Map of section name → extracted content (without marker lines). */
+  sections: Record<string, string>
+  /** Map of component name → extracted content (without marker lines). */
+  components: Record<string, string>
+  /** Whether the DESIGN.md has any markers at all. */
+  hasMarkers: boolean
+}
+
+/**
+ * Parse a DESIGN.md body (no frontmatter) into sections and components
+ * using the two-layer HTML comment marker convention:
+ *   <!-- @section:<name>:start --> … <!-- @section:<name>:end -->
+ *   <!-- @component:<name>:start --> … <!-- @component:<name>:end -->
+ *
+ * Returns an object with empty maps and hasMarkers=false when no markers found.
+ */
+export function parseDesignSections(body: string): DesignSections {
+  const sections: Record<string, string> = {}
+  const components: Record<string, string> = {}
+
+  const sectionRe = /<!--\s*@section:(\w[\w-]*):start\s*-->([\s\S]*?)<!--\s*@section:\1:end\s*-->/g
+  const componentRe = /<!--\s*@component:(\w[\w-]*):start\s*-->([\s\S]*?)<!--\s*@component:\1:end\s*-->/g
+
+  let hasMarkers = false
+  let match: RegExpExecArray | null
+
+  while ((match = sectionRe.exec(body)) !== null) {
+    hasMarkers = true
+    sections[match[1]] = match[2].trim()
+  }
+
+  while ((match = componentRe.exec(body)) !== null) {
+    hasMarkers = true
+    components[match[1]] = match[2].trim()
+  }
+
+  return { sections, components, hasMarkers }
+}
+
+/**
+ * Generate a compact Component Index table from parsed components.
+ * Lists each component name with a one-line description (first non-empty
+ * text line of the component block, stripped of markdown heading markers).
+ */
+export function generateComponentIndex(components: Record<string, string>): string {
+  const names = Object.keys(components)
+  if (names.length === 0) return ""
+
+  const rows = names.map((name) => {
+    const body = components[name]
+    // Extract first non-empty non-marker line as a short description
+    const firstLine = body
+      .split("\n")
+      .map((l) => l.trim())
+      .find((l) => l && !l.startsWith("<!--") && !l.startsWith("```"))
+    // Strip markdown heading markers
+    const desc = firstLine
+      ? firstLine.replace(/^#+\s*/, "").replace(/\(.*?\)/, "").trim()
+      : ""
+    return `| \`${name}\` | ${desc} |`
+  })
+
+  return [
+    "### Component Index",
+    "",
+    "| Component | Description |",
+    "|---|---|",
+    ...rows,
+    "",
+    "_Use `revela-designs` tool with `action: \"read\"` and `component: \"<name>\"` to get full CSS/HTML for any component._",
+  ].join("\n")
+}
+
+/**
+ * Get the raw text of a named section from a DESIGN.md.
+ * Throws if the design is not installed or the section doesn't exist.
+ */
+export function getDesignSection(sectionName: string, designName?: string): string {
+  const name = designName || activeDesign()
+  const mdPath = join(DESIGNS_DIR, name, "DESIGN.md")
+  if (!existsSync(mdPath)) {
+    throw new Error(`Design '${name}' is not installed`)
+  }
+  const text = readFileSync(mdPath, "utf-8")
+  const { body } = parseFrontmatter(text)
+  const { sections, hasMarkers } = parseDesignSections(body)
+
+  if (!hasMarkers) {
+    throw new Error(`Design '${name}' has no markers — use getDesignSkillMd() for full text`)
+  }
+  if (!(sectionName in sections)) {
+    throw new Error(`Section '${sectionName}' not found in design '${name}'`)
+  }
+  return sections[sectionName]
+}
+
+/**
+ * Get the raw text of one or more named components from a DESIGN.md.
+ * @param componentNames - Comma-separated component names or an array.
+ * @param designName - Design to read from (defaults to active).
+ */
+export function getDesignComponent(
+  componentNames: string | string[],
+  designName?: string,
+): string {
+  const name = designName || activeDesign()
+  const mdPath = join(DESIGNS_DIR, name, "DESIGN.md")
+  if (!existsSync(mdPath)) {
+    throw new Error(`Design '${name}' is not installed`)
+  }
+  const text = readFileSync(mdPath, "utf-8")
+  const { body } = parseFrontmatter(text)
+  const { components, hasMarkers } = parseDesignSections(body)
+
+  if (!hasMarkers) {
+    throw new Error(`Design '${name}' has no markers — use getDesignSkillMd() for full text`)
+  }
+
+  const names = Array.isArray(componentNames)
+    ? componentNames
+    : componentNames.split(",").map((s) => s.trim())
+
+  const parts: string[] = []
+  for (const compName of names) {
+    if (!(compName in components)) {
+      throw new Error(`Component '${compName}' not found in design '${name}'`)
+    }
+    parts.push(`### Component: ${compName}\n\n${components[compName]}`)
+  }
+  return parts.join("\n\n---\n\n")
+}
+
+/** Remove an installed design. Throws if not found. */
+export function removeDesign(name: string): void {
+  const dir = join(DESIGNS_DIR, name)
+  if (!existsSync(dir)) {
+    throw new Error(`Design '${name}' is not installed`)
+  }
+  rmSync(dir, { recursive: true, force: true })
+  // Reset active design if it was the removed one
+  if (activeDesign() === name) {
+    activateDesign(DEFAULT_DESIGN)
+  }
+}
+
+/**
+ * Install a design from a source.
+ *
+ * Supported sources:
+ * - Local path (starts with `./ ` or `/` or exists on disk)
+ * - URL (starts with `http://` or `https://`) — downloads zip
+ * - GitHub shorthand `github:user/repo` — converted to zip URL
+ *
+ * Returns the installed design name.
+ */
+export async function installDesign(
+  source: string,
+  name?: string,
+): Promise<string> {
+  if (source.startsWith("http://") || source.startsWith("https://")) {
+    return installFromUrl(source, name)
+  }
+  if (source.startsWith("github:")) {
+    const repo = source.slice("github:".length)
+    const url = `https://github.com/${repo}/archive/refs/heads/main.zip`
+    return installFromUrl(url, name)
+  }
+  // Local path
+  return installFromPath(source, name)
+}
+
+// ---------------------------------------------------------------------------
+// Private helpers
+// ---------------------------------------------------------------------------
+
+function designExists(name: string): boolean {
+  const dir = join(DESIGNS_DIR, name)
+  return existsSync(dir) && existsSync(join(dir, "DESIGN.md"))
+}
+
+function installFromPath(srcPath: string, name?: string): string {
+  const resolved = resolve(srcPath)
+  if (!existsSync(resolved)) {
+    throw new Error(`Path does not exist: ${resolved}`)
+  }
+  if (!existsSync(join(resolved, "DESIGN.md"))) {
+    throw new Error(`No DESIGN.md found in ${resolved}`)
+  }
+  const info = parseDesignFile(join(resolved, "DESIGN.md"))
+  const designName = name || info?.name || basename(resolved)
+  const target = join(DESIGNS_DIR, designName)
+
+  mkdirSync(DESIGNS_DIR, { recursive: true })
+  if (existsSync(target)) {
+    rmSync(target, { recursive: true, force: true })
+  }
+  cpSync(resolved, target, { recursive: true })
+  return designName
+}
+
+async function installFromUrl(url: string, name?: string): Promise<string> {
+  // Download zip to temp dir
+  const tmp = join(tmpdir(), `revela-design-${Date.now()}`)
+  mkdirSync(tmp, { recursive: true })
+
+  try {
+    const zipPath = join(tmp, "design.zip")
+    const response = await fetch(url)
+    if (!response.ok) {
+      throw new Error(`Failed to download: ${response.status} ${response.statusText}`)
+    }
+    const buffer = new Uint8Array(await response.arrayBuffer())
+    writeFileSync(zipPath, buffer)
+
+    // Extract using Bun's built-in or system unzip
+    const extractDir = join(tmp, "extracted")
+    mkdirSync(extractDir)
+
+    // Use system unzip (available on macOS/Linux)
+    const proc = Bun.spawnSync(["unzip", "-q", "-o", zipPath, "-d", extractDir])
+    if (proc.exitCode !== 0) {
+      throw new Error(`Failed to extract zip: ${proc.stderr.toString()}`)
+    }
+
+    // Find DESIGN.md in extracted contents (GitHub zips wrap in a subdirectory)
+    const candidates = [extractDir]
+    for (const entry of readdirSync(extractDir)) {
+      const p = join(extractDir, entry)
+      if (statSync(p).isDirectory()) candidates.push(p)
+    }
+
+    for (const candidate of candidates) {
+      if (existsSync(join(candidate, "DESIGN.md"))) {
+        return installFromPath(candidate, name)
+      }
+    }
+    throw new Error("No DESIGN.md found inside the downloaded zip")
+  } finally {
+    rmSync(tmp, { recursive: true, force: true })
+  }
+}