@cyber-dash-tech/revela 0.1.0

package/lib/domain/domains.ts

@@ -0,0 +1,258 @@
+/**
+ * DomainManager — manage revela domain definitions (formerly "industries").
+ *
+ * Domains are stored in ~/.config/revela/domains/<name>/.
+ * Each domain directory contains DOMAIN.md (required).
+ *
+ * Built-in domains are shipped with the npm package under domains/ and seeded
+ * to the config directory on first run.
+ *
+ * NOTE: For backward compatibility, the .md files inside each domain directory
+ * are still named INDUSTRY.md. The config key `activeIndustry` is used as
+ * fallback for `activeDomain`.
+ */
+
+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 {
+  DOMAINS_DIR,
+  DEFAULT_DOMAIN,
+  loadConfig,
+  saveConfig,
+} from "../config"
+import { childLog } from "../log"
+
+const domainLog = childLog("domains")
+
+// Seed directory: built-in domains shipped with this package.
+const SEED_DIR = resolve(__dirname, "../..", "domains")
+
+/** The markdown filename inside each domain directory. */
+const DOMAIN_FILE = "INDUSTRY.md"
+
+export interface DomainInfo {
+  name: string
+  description: string
+  author: string
+  version: string
+  skillText: string
+}
+
+// ---------------------------------------------------------------------------
+// Seed
+// ---------------------------------------------------------------------------
+
+/**
+ * Copy built-in domains from the package to ~/.config/revela/domains/.
+ * Always overwrites to keep bundled domains up to date.
+ * User-created domains (not in the seed directory) are never touched.
+ */
+export function seedBuiltinDomains(): void {
+  if (!existsSync(SEED_DIR)) return
+  mkdirSync(DOMAINS_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, DOMAIN_FILE))) continue
+
+    const dst = join(DOMAINS_DIR, entry)
+    mkdirSync(dst, { recursive: true })
+    cpSync(src, dst, { recursive: true, force: true })
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Parse
+// ---------------------------------------------------------------------------
+
+/** Parse an INDUSTRY.md file into DomainInfo. Returns null on any error. */
+export function parseDomainFile(filePath: string): DomainInfo | 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) {
+    domainLog.warn("failed to parse domain file — skipping", {
+      filePath,
+      error: e instanceof Error ? e.message : String(e),
+    })
+    return null
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/** List all installed domains, sorted by name. */
+export function listDomains(): DomainInfo[] {
+  if (!existsSync(DOMAINS_DIR)) return []
+  const results: DomainInfo[] = []
+
+  for (const entry of readdirSync(DOMAINS_DIR).sort()) {
+    const dir = join(DOMAINS_DIR, entry)
+    if (!statSync(dir).isDirectory()) continue
+    const mdPath = join(dir, DOMAIN_FILE)
+    if (!existsSync(mdPath)) continue
+    const info = parseDomainFile(mdPath)
+    if (info) results.push(info)
+  }
+  return results
+}
+
+/** Get the name of the currently active domain. */
+export function activeDomain(): string {
+  const cfg = loadConfig()
+  return cfg.activeDomain || cfg.activeIndustry || DEFAULT_DOMAIN
+}
+
+/** Set the active domain. Throws if domain is not installed. */
+export function activateDomain(name: string): void {
+  if (!domainExists(name)) {
+    throw new Error(`Domain '${name}' is not installed`)
+  }
+  const cfg = loadConfig()
+  cfg.activeDomain = name
+  saveConfig(cfg)
+}
+
+/** Get the skill text body from a domain's INDUSTRY.md. */
+export function getDomainSkillMd(name?: string): string {
+  const domainName = name || activeDomain()
+  const mdPath = join(DOMAINS_DIR, domainName, DOMAIN_FILE)
+  if (!existsSync(mdPath)) {
+    throw new Error(`Domain '${domainName}' is not installed`)
+  }
+  const info = parseDomainFile(mdPath)
+  if (!info) {
+    throw new Error(`Failed to parse ${DOMAIN_FILE} for '${domainName}'`)
+  }
+  return info.skillText
+}
+
+/** Remove an installed domain. Throws if not found or is the protected default. */
+export function removeDomain(name: string): void {
+  if (name === DEFAULT_DOMAIN) {
+    throw new Error(`Cannot remove the built-in '${DEFAULT_DOMAIN}' domain`)
+  }
+  const dir = join(DOMAINS_DIR, name)
+  if (!existsSync(dir)) {
+    throw new Error(`Domain '${name}' is not installed`)
+  }
+  rmSync(dir, { recursive: true, force: true })
+  // Reset active domain if it was the removed one
+  if (activeDomain() === name) {
+    activateDomain(DEFAULT_DOMAIN)
+  }
+}
+
+/**
+ * Install a domain 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 domain name.
+ */
+export async function installDomain(
+  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 domainExists(name: string): boolean {
+  const dir = join(DOMAINS_DIR, name)
+  return existsSync(dir) && existsSync(join(dir, DOMAIN_FILE))
+}
+
+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, DOMAIN_FILE))) {
+    throw new Error(`No ${DOMAIN_FILE} found in ${resolved}`)
+  }
+  const info = parseDomainFile(join(resolved, DOMAIN_FILE))
+  const domainName = name || info?.name || basename(resolved)
+  const target = join(DOMAINS_DIR, domainName)
+
+  mkdirSync(DOMAINS_DIR, { recursive: true })
+  if (existsSync(target)) {
+    rmSync(target, { recursive: true, force: true })
+  }
+  cpSync(resolved, target, { recursive: true })
+  return domainName
+}
+
+async function installFromUrl(url: string, name?: string): Promise<string> {
+  const tmp = join(tmpdir(), `revela-domain-${Date.now()}`)
+  mkdirSync(tmp, { recursive: true })
+
+  try {
+    const zipPath = join(tmp, "domain.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)
+
+    const extractDir = join(tmp, "extracted")
+    mkdirSync(extractDir)
+
+    const proc = Bun.spawnSync(["unzip", "-q", "-o", zipPath, "-d", extractDir])
+    if (proc.exitCode !== 0) {
+      throw new Error(`Failed to extract zip: ${proc.stderr.toString()}`)
+    }
+
+    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, DOMAIN_FILE))) {
+        return installFromPath(candidate, name)
+      }
+    }
+    throw new Error(`No ${DOMAIN_FILE} found inside the downloaded zip`)
+  } finally {
+    rmSync(tmp, { recursive: true, force: true })
+  }
+}

package/lib/frontmatter.ts

@@ -0,0 +1,63 @@
+/**
+ * Minimal YAML frontmatter parser.
+ *
+ * Handles the simple `key: value` format used by DESIGN.md / DOMAIN.md files.
+ * No dependency on external YAML libraries.
+ */
+
+export interface Frontmatter {
+  /** Key-value pairs from the YAML block between `---` fences. */
+  meta: Record<string, string>
+  /** Everything after the closing `---`, trimmed. */
+  body: string
+}
+
+/**
+ * Parse a markdown file with optional YAML frontmatter.
+ *
+ * Format:
+ * ```
+ * ---
+ * key1: value1
+ * key2: value2
+ * ---
+ *
+ * Body text...
+ * ```
+ *
+ * If the file does not start with `---`, the entire content is returned as body
+ * with an empty meta object.
+ */
+export function parseFrontmatter(text: string): Frontmatter {
+  const lines = text.split("\n")
+
+  if (!lines.length || lines[0].trim() !== "---") {
+    return { meta: {}, body: text.trim() }
+  }
+
+  const meta: Record<string, string> = {}
+  let endIdx = -1
+
+  for (let i = 1; i < lines.length; i++) {
+    if (lines[i].trim() === "---") {
+      endIdx = i
+      break
+    }
+    const colonPos = lines[i].indexOf(":")
+    if (colonPos !== -1) {
+      const key = lines[i].slice(0, colonPos).trim()
+      const value = lines[i].slice(colonPos + 1).trim()
+      if (key) {
+        meta[key] = value
+      }
+    }
+  }
+
+  if (endIdx === -1) {
+    // No closing ---, treat entire content as body
+    return { meta: {}, body: text.trim() }
+  }
+
+  const body = lines.slice(endIdx + 1).join("\n").trim()
+  return { meta, body }
+}

package/lib/log.ts

@@ -0,0 +1,35 @@
+import { Logger } from "tslog"
+
+/**
+ * Revela structured logger (tslog).
+ *
+ * Log levels:
+ *   0 = silly, 1 = trace, 2 = debug, 3 = info, 4 = warn, 5 = error, 6 = fatal
+ *
+ * Set REVELA_DEBUG=1 to enable debug-level output (minLevel 2).
+ * Default minLevel is 3 (info) in production.
+ */
+const minLevel = process.env.REVELA_DEBUG === "1" ? 2 : 3
+
+export const log = new Logger({
+  name: "revela",
+  minLevel,
+  type: "json",
+  hideLogPositionForProduction: true,
+  overwrite: {
+    transportJSON: (logObj: unknown) => {
+      process.stderr.write(JSON.stringify(logObj) + "\n")
+    },
+  },
+})
+
+/**
+ * Create a child logger for a specific sub-module.
+ *
+ * @example
+ * const qaLog = childLog("qa")
+ * qaLog.info("measuring slides", { file: htmlPath })
+ */
+export function childLog(name: string) {
+  return log.getSubLogger({ name })
+}

package/lib/prompt-builder.ts

@@ -0,0 +1,194 @@
+/**
+ * Prompt builder — assembles the three-layer system prompt.
+ *
+ * Layer 1: SKILL.md     — core protocol (conversation flow, HTML rules, quality)
+ * Layer 2: DOMAIN.md    — domain knowledge (report structure, terminology)
+ * Layer 3: DESIGN.md    — visual style (colors, fonts, animations, layout)
+ *
+ * When the active DESIGN.md has @section markers, only the global section,
+ * layouts section, and a generated component index are injected into the
+ * system prompt. Components, charts, and guide sections are available on
+ * demand via the revela-designs tool read action.
+ *
+ * When no markers are present (third-party designs), the full DESIGN.md body
+ * is injected unchanged (backward-compatible fallback).
+ *
+ * The combined prompt is written to ~/.config/revela/_active-prompt.md
+ * and referenced by agents via `{file:~/.config/revela/_active-prompt.md}`.
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "fs"
+import { join, resolve } from "path"
+import {
+  CONFIG_DIR,
+  DESIGNS_DIR,
+  ACTIVE_PROMPT_FILE,
+} from "./config"
+import {
+  activeDesign,
+  getDesignSkillMd,
+  parseDesignSections,
+  generateComponentIndex,
+} from "./design/designs"
+import { activeDomain, getDomainSkillMd } from "./domain/domains"
+import { parseFrontmatter } from "./frontmatter"
+import { SLIDE_TYPES, type SlideType } from "./qa/checks"
+import { childLog } from "./log"
+
+const promptLog = childLog("prompt-builder")
+
+/** Path to SKILL.md shipped with this package. */
+const SKILL_MD_PATH = resolve(__dirname, "..", "skill", "SKILL.md")
+
+/**
+ * Human-readable descriptions for each slide type.
+ * Used to generate the data-slide-type table injected into SKILL.md.
+ * Kept here (not in checks.ts) — these are prose for the AI, not QA logic.
+ */
+const SLIDE_TYPE_DESCRIPTIONS: Record<SlideType, string> = {
+  cover: "Title / opening slide",
+  toc: "Table of contents",
+  content: "Regular content slides (default)",
+  summary: "Key takeaways slide",
+  closing: "Thank-you / Q&A / contact slide",
+  divider: "Section-break / transition slide",
+  "thank-you": "Alias for `closing`",
+}
+
+/**
+ * Build the combined system prompt and write it to _active-prompt.md.
+ *
+ * @param designName - Override design (defaults to active)
+ * @param domainName - Override domain (defaults to active)
+ * @returns The path to the written file.
+ */
+export function buildPrompt(designName?: string, domainName?: string): string {
+  const design = designName || activeDesign()
+  const domain = domainName || activeDomain()
+
+  // Layer 1 — SKILL.md (with dynamic slide-type table injected)
+  let coreSkill = readFileSync(SKILL_MD_PATH, "utf-8")
+  coreSkill = injectSlideTypes(coreSkill)
+
+  // Check for preview.html
+  const designDir = join(DESIGNS_DIR, design)
+  const hasPreview = existsSync(join(designDir, "preview.html"))
+  const previewLine = hasPreview
+    ? "<!--   - preview.html — canonical visual reference (read this before generating slides) -->"
+    : "<!--   - (no preview.html for this design) -->"
+
+  // Layer 2 — DOMAIN.md skill text (may be empty for "general")
+  let domainSkill = ""
+  try {
+    domainSkill = getDomainSkillMd(domain)
+  } catch (e) {
+    // Domain not installed or empty — proceed without domain layer
+    promptLog.warn("domain skill not found — building without domain layer", {
+      domain,
+      error: e instanceof Error ? e.message : String(e),
+    })
+  }
+
+  // Layer 3 — DESIGN.md: marker-aware or full-text fallback
+  const designSkill = buildDesignLayer(design)
+
+  // Assemble header
+  const header =
+    `<!-- Active design: ${design} -->\n` +
+    `<!-- Active domain: ${domain} -->\n` +
+    `<!-- Design files: ${designDir}/ -->\n` +
+    `<!--   - DESIGN.md — metadata + style instructions (injected below) -->\n` +
+    `${previewLine}\n\n`
+
+  // Three-layer concatenation: Header → SKILL → Domain → Design
+  const parts = [header, coreSkill]
+  if (domainSkill) {
+    parts.push(`\n\n---\n\n${domainSkill}`)
+  }
+  parts.push(`\n\n---\n\n${designSkill}`)
+
+  const prompt = parts.join("")
+
+  // Write to _active-prompt.md
+  mkdirSync(CONFIG_DIR, { recursive: true })
+  writeFileSync(ACTIVE_PROMPT_FILE, prompt, "utf-8")
+  promptLog.info("prompt rebuilt", { design, domain, bytes: prompt.length })
+
+  return ACTIVE_PROMPT_FILE
+}
+
+/**
+ * Build the design layer text.
+ *
+ * If the DESIGN.md has markers:
+ *   - Always include @section:global
+ *   - Always include @section:layouts (layout primitives — always needed)
+ *   - Include a generated Component Index table (lightweight catalog)
+ *   - Omit @section:components detail, @section:charts, @section:guide
+ *     (available on demand via revela-designs tool)
+ *
+ * If no markers: return the full DESIGN.md body unchanged.
+ */
+function buildDesignLayer(designName: string): string {
+  const mdPath = join(DESIGNS_DIR, designName, "DESIGN.md")
+  if (!existsSync(mdPath)) {
+    throw new Error(`Design '${designName}' is not installed`)
+  }
+
+  const raw = readFileSync(mdPath, "utf-8")
+  const { body } = parseFrontmatter(raw)
+  const { sections, components, hasMarkers } = parseDesignSections(body)
+
+  if (!hasMarkers) {
+    // Backward-compatible: full text injection
+    return body
+  }
+
+  const layerParts: string[] = []
+
+  // 1. Global section (colors, typography, CSS, JS class, HTML structure)
+  if (sections["global"]) {
+    layerParts.push(sections["global"])
+  }
+
+  // 2. Component Index — compact catalog
+  const index = generateComponentIndex(components)
+  if (index) {
+    layerParts.push(index)
+  }
+
+  // 3. Layouts section — always resident (needed for every slide)
+  if (sections["layouts"]) {
+    layerParts.push(sections["layouts"])
+  }
+
+  // 4. On-demand note
+  layerParts.push(
+    [
+      "### On-Demand Design Sections",
+      "",
+      "The following design sections are available on demand. Fetch them with",
+      "the `revela-designs` tool (`action: \"read\"`) before using them:",
+      "",
+      "| Section | Fetch with |",
+      "|---|---|",
+      "| Component CSS/HTML details | `component: \"<name>\"` (see Component Index above) |",
+      "| Data Visualization (ECharts) | `section: \"charts\"` |",
+      "| Composition Guide & Do/Don't | `section: \"guide\"` |",
+    ].join("\n"),
+  )
+
+  return layerParts.join("\n\n---\n\n")
+}
+
+/**
+ * Replace the <!-- @slide-types --> placeholder in SKILL.md with a generated
+ * markdown table built from SLIDE_TYPES (single source of truth in checks.ts).
+ */
+function injectSlideTypes(skillMd: string): string {
+  const rows = SLIDE_TYPES.map(
+    (t) => `| \`${t}\` | ${SLIDE_TYPE_DESCRIPTIONS[t]} |`,
+  )
+  const table = ["| Value | Use for |", "|-------|---------|", ...rows].join("\n")
+  return skillMd.replace("<!-- @slide-types -->", table)
+}