@cyber-dash-tech/revela 0.3.1 → 0.4.0

package/lib/media/save.ts

@@ -0,0 +1,273 @@
+import {
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "fs"
+import { dirname, join, relative, resolve, sep } from "path"
+import { downloadImageFromUrl, inferImageExtension } from "./download"
+import type {
+  MediaAssetRecord,
+  MediaManifest,
+  MediaSaveInput,
+  MediaSaveResult,
+  MediaStatus,
+} from "./types"
+
+function nowIso(): string {
+  return new Date().toISOString()
+}
+
+function slugify(value: string): string {
+  return value
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+}
+
+function ensureInsideWorkspace(pathValue: string, workspaceDir: string): string {
+  const abs = resolve(workspaceDir, pathValue)
+  const root = resolve(workspaceDir)
+  if (abs !== root && !abs.startsWith(root + sep)) {
+    throw new Error("sourcePath must be within workspace")
+  }
+  return abs
+}
+
+function readManifest(manifestPath: string, topic: string): MediaManifest {
+  if (!existsSync(manifestPath)) {
+    return { topic, updatedAt: nowIso(), assets: [] }
+  }
+
+  const parsed = JSON.parse(readFileSync(manifestPath, "utf-8")) as Partial<MediaManifest>
+  return {
+    topic,
+    updatedAt: typeof parsed.updatedAt === "string" ? parsed.updatedAt : nowIso(),
+    assets: Array.isArray(parsed.assets) ? parsed.assets as MediaAssetRecord[] : [],
+  }
+}
+
+function buildFailureRecord(
+  input: MediaSaveInput,
+  topic: string,
+  status: Exclude<MediaStatus, "success">,
+  failureReason: string,
+  sourcePath?: string,
+): MediaAssetRecord {
+  return {
+    id: slugify(input.id),
+    type: "image",
+    purpose: input.purpose,
+    brief: input.brief,
+    status,
+    path: null,
+    sourceUrl: input.sourceUrl,
+    sourcePath,
+    intendedSection: input.intendedSection,
+    alt: input.alt,
+    notes: input.notes,
+    failureReason,
+    savedAt: nowIso(),
+  }
+}
+
+function upsertAsset(manifest: MediaManifest, record: MediaAssetRecord): { manifest: MediaManifest; previous?: MediaAssetRecord } {
+  const assets = [...manifest.assets]
+  const index = assets.findIndex((asset) => asset.id === record.id)
+  const previous = index === -1 ? undefined : assets[index]
+  if (index === -1) assets.push(record)
+  else assets[index] = record
+  return {
+    previous,
+    manifest: {
+      topic: manifest.topic,
+      updatedAt: nowIso(),
+      assets,
+    },
+  }
+}
+
+function writeManifest(manifestPath: string, manifest: MediaManifest): void {
+  mkdirSync(dirname(manifestPath), { recursive: true })
+  writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, "utf-8")
+}
+
+function saveFailureResult(
+  input: MediaSaveInput,
+  workspaceDir: string,
+  topic: string,
+  manifestPath: string,
+  status: Exclude<MediaStatus, "success">,
+  failureReason: string,
+  sourcePath?: string,
+): MediaSaveResult {
+  const manifest = readManifest(manifestPath, topic)
+  const existing = manifest.assets.find((asset) => asset.id === slugify(input.id))
+  const record = existing?.path
+    ? {
+      ...existing,
+      sourceUrl: input.sourceUrl ?? existing.sourceUrl,
+      sourcePath: sourcePath ?? existing.sourcePath,
+      alt: input.alt ?? existing.alt,
+      notes: input.notes ?? existing.notes,
+      failureReason,
+    }
+    : buildFailureRecord(input, topic, status, failureReason, sourcePath)
+  const { manifest: nextManifest, previous } = upsertAsset(manifest, record)
+  writeManifest(manifestPath, nextManifest)
+
+  if (!existing?.path && previous?.path) {
+    rmSync(join(workspaceDir, previous.path), { force: true })
+  }
+
+  return {
+    ok: true,
+    assetId: record.id,
+    status,
+    path: null,
+    manifestPath: relative(workspaceDir, manifestPath),
+    updated: true,
+  }
+}
+
+export async function saveMediaAsset(input: MediaSaveInput, workspaceDir: string): Promise<MediaSaveResult> {
+  try {
+    const topic = slugify(input.topic)
+    const assetId = slugify(input.id)
+    if (!topic) return { ok: false, error: "topic is required" }
+    if (!assetId) return { ok: false, error: "id is required" }
+    if (input.type !== "image") return { ok: false, error: "type must be 'image'" }
+
+    const topicDir = join(workspaceDir, "assets", topic)
+    const mediaDir = join(topicDir, "media")
+    const manifestPath = join(topicDir, "media-manifest.json")
+    mkdirSync(mediaDir, { recursive: true })
+
+    const relativeSourcePath = input.sourcePath
+      ? relative(workspaceDir, ensureInsideWorkspace(input.sourcePath, workspaceDir))
+      : undefined
+
+    if (input.status !== "success") {
+      if (!input.failureReason?.trim()) {
+        return { ok: false, error: "failureReason is required when status is not 'success'" }
+      }
+      return saveFailureResult(
+        input,
+        workspaceDir,
+        topic,
+        manifestPath,
+        input.status,
+        input.failureReason.trim(),
+        relativeSourcePath,
+      )
+    }
+
+    if (!input.sourcePath && !input.sourceUrl) {
+      return { ok: false, error: "sourcePath or sourceUrl is required when status is 'success'" }
+    }
+
+    let buffer: Buffer
+    let extension: string | null = null
+
+    if (input.sourcePath) {
+      const absPath = ensureInsideWorkspace(input.sourcePath, workspaceDir)
+      if (!existsSync(absPath)) {
+        return { ok: false, error: `sourcePath not found: ${input.sourcePath}` }
+      }
+      extension = inferImageExtension(null, absPath)
+      if (!extension) {
+        return { ok: false, error: `unsupported local image type: ${input.sourcePath}` }
+      }
+      const destinationPath = join(mediaDir, `${assetId}${extension}`)
+      const manifest = readManifest(manifestPath, topic)
+      const previous = manifest.assets.find((asset) => asset.id === assetId)
+      copyFileSync(absPath, destinationPath)
+      const record: MediaAssetRecord = {
+        id: assetId,
+        type: "image",
+        purpose: input.purpose,
+        brief: input.brief,
+        status: "success",
+        path: relative(workspaceDir, destinationPath),
+        sourceUrl: input.sourceUrl,
+        sourcePath: relativeSourcePath,
+        intendedSection: input.intendedSection,
+        alt: input.alt,
+        notes: input.notes,
+        savedAt: nowIso(),
+      }
+      const { manifest: nextManifest } = upsertAsset(manifest, record)
+      writeManifest(manifestPath, nextManifest)
+      if (previous?.path && previous.path !== record.path) {
+        rmSync(join(workspaceDir, previous.path), { force: true })
+      }
+      return {
+        ok: true,
+        assetId,
+        status: "success",
+        path: record.path,
+        manifestPath: relative(workspaceDir, manifestPath),
+        updated: true,
+      }
+    }
+
+    try {
+      const downloaded = await downloadImageFromUrl(input.sourceUrl!)
+      buffer = downloaded.buffer
+      extension = downloaded.extension
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error)
+      if (message === "INVALID_URL") {
+        return saveFailureResult(input, workspaceDir, topic, manifestPath, "invalid-url", "Invalid image URL")
+      }
+      return saveFailureResult(
+        input,
+        workspaceDir,
+        topic,
+        manifestPath,
+        "cannot-download",
+        `Failed to download image: ${message}`,
+      )
+    }
+
+    const destinationPath = join(mediaDir, `${assetId}${extension}`)
+    const manifest = readManifest(manifestPath, topic)
+    const previous = manifest.assets.find((asset) => asset.id === assetId)
+    writeFileSync(destinationPath, new Uint8Array(buffer))
+    const record: MediaAssetRecord = {
+      id: assetId,
+      type: "image",
+      purpose: input.purpose,
+      brief: input.brief,
+      status: "success",
+      path: relative(workspaceDir, destinationPath),
+      sourceUrl: input.sourceUrl,
+      sourcePath: relativeSourcePath,
+      intendedSection: input.intendedSection,
+      alt: input.alt,
+      notes: input.notes,
+      savedAt: nowIso(),
+    }
+    const { manifest: nextManifest } = upsertAsset(manifest, record)
+    writeManifest(manifestPath, nextManifest)
+    if (previous?.path && previous.path !== record.path) {
+      rmSync(join(workspaceDir, previous.path), { force: true })
+    }
+
+    return {
+      ok: true,
+      assetId,
+      status: "success",
+      path: record.path,
+      manifestPath: relative(workspaceDir, manifestPath),
+      updated: true,
+    }
+  } catch (error) {
+    return {
+      ok: false,
+      error: error instanceof Error ? error.message : String(error),
+    }
+  }
+}

package/lib/media/types.ts

@@ -0,0 +1,54 @@
+export type MediaPurpose = "hero" | "illustration" | "portrait" | "logo" | "screenshot"
+
+export type MediaStatus = "success" | "cannot-download" | "invalid-url" | "cannot-generate"
+
+export interface MediaSaveInput {
+  topic: string
+  id: string
+  type: "image"
+  purpose: MediaPurpose
+  brief: string
+  status: MediaStatus
+  intendedSection?: string
+  sourcePath?: string
+  sourceUrl?: string
+  alt?: string
+  notes?: string
+  failureReason?: string
+}
+
+export interface MediaAssetRecord {
+  id: string
+  type: "image"
+  purpose: MediaPurpose
+  brief: string
+  status: MediaStatus
+  path: string | null
+  sourceUrl?: string
+  sourcePath?: string
+  intendedSection?: string
+  alt?: string
+  notes?: string
+  failureReason?: string
+  savedAt: string
+}
+
+export interface MediaManifest {
+  topic: string
+  updatedAt: string
+  assets: MediaAssetRecord[]
+}
+
+export type MediaSaveResult =
+  | {
+    ok: true
+    assetId: string
+    status: MediaStatus
+    path: string | null
+    manifestPath: string
+    updated: boolean
+  }
+  | {
+    ok: false
+    error: string
+  }

package/lib/research/image-leads.ts

@@ -0,0 +1,175 @@
+import { existsSync, readdirSync, readFileSync } from "fs"
+import { basename, join } from "path"
+
+export type ResearchImageUse = "logo" | "portrait" | "screenshot" | "unknown"
+
+export interface ResearchImageLead {
+  candidateId: string
+  topic: string
+  axis: string
+  sourceFile: string
+  description: string
+  url: string
+  alt: string
+  use: ResearchImageUse
+  line: number
+  valid: boolean
+  warnings: string[]
+}
+
+export interface ListResearchImageLeadOptions {
+  uses?: string[]
+  axis?: string[]
+}
+
+export interface ResearchImageLeadListResult {
+  topic: string
+  items: ResearchImageLead[]
+  warnings: string[]
+}
+
+const LEAD_LINE_RE = /^-\s*(.+?):\s*(\S+)(?:\s*\|\s*Alt:\s*(.*?))?(?:\s*\|\s*Use:\s*(.*?))?\s*$/
+
+function slugify(value: string): string {
+  return value
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+}
+
+function normalizeUse(value: string | undefined): ResearchImageUse {
+  const normalized = (value ?? "").trim().toLowerCase()
+  if (normalized === "logo" || normalized === "portrait" || normalized === "screenshot") {
+    return normalized
+  }
+  return "unknown"
+}
+
+function normalizeAxisFilter(values: string[] | undefined): string[] | undefined {
+  if (!values?.length) return undefined
+  const normalized = values
+    .map((value) => slugify(value))
+    .filter(Boolean)
+  return normalized.length ? normalized : undefined
+}
+
+function normalizeUseFilter(values: string[] | undefined): ResearchImageUse[] | undefined {
+  if (!values?.length) return undefined
+  const normalized = values
+    .map((value) => normalizeUse(value))
+  return normalized.length ? normalized : undefined
+}
+
+function isHttpUrl(value: string): boolean {
+  try {
+    const url = new URL(value)
+    return url.protocol === "http:" || url.protocol === "https:"
+  } catch {
+    return false
+  }
+}
+
+function shouldIncludeLead(lead: ResearchImageLead, options?: ListResearchImageLeadOptions): boolean {
+  const uses = normalizeUseFilter(options?.uses)
+  const axis = normalizeAxisFilter(options?.axis)
+  if (uses?.length && !uses.includes(lead.use)) return false
+  if (axis?.length && !axis.includes(lead.axis)) return false
+  return true
+}
+
+function parseImageSection(
+  topic: string,
+  axis: string,
+  sourceFile: string,
+  content: string,
+): { items: ResearchImageLead[]; warnings: string[] } {
+  const lines = content.split(/\r?\n/)
+  const items: ResearchImageLead[] = []
+  const warnings: string[] = []
+  let inImagesSection = false
+  let candidateIndex = 0
+
+  for (let index = 0; index < lines.length; index++) {
+    const line = lines[index]
+    const trimmed = line.trim()
+
+    if (/^##\s+Images\s*$/i.test(trimmed)) {
+      inImagesSection = true
+      continue
+    }
+
+    if (inImagesSection && /^##\s+/.test(trimmed)) {
+      break
+    }
+
+    if (!inImagesSection || !trimmed.startsWith("-")) continue
+    if (trimmed === "- None") continue
+
+    const match = trimmed.match(LEAD_LINE_RE)
+    if (!match) {
+      warnings.push(`${sourceFile}:${index + 1} could not parse image lead`)
+      continue
+    }
+
+    candidateIndex += 1
+    const description = match[1].trim()
+    const url = match[2].trim()
+    const alt = (match[3] ?? "").trim()
+    const use = normalizeUse(match[4])
+    const itemWarnings: string[] = []
+    const valid = isHttpUrl(url)
+
+    if (!valid) itemWarnings.push("invalid-url")
+    if (use === "unknown") itemWarnings.push("unknown-use")
+
+    items.push({
+      candidateId: `${axis}:${candidateIndex}`,
+      topic,
+      axis,
+      sourceFile,
+      description,
+      url,
+      alt,
+      use,
+      line: index + 1,
+      valid,
+      warnings: itemWarnings,
+    })
+  }
+
+  return { items, warnings }
+}
+
+export function listResearchImageLeads(
+  topic: string,
+  workspaceDir: string,
+  options?: ListResearchImageLeadOptions,
+): ResearchImageLeadListResult {
+  const topicSlug = slugify(topic)
+  const researchDir = join(workspaceDir, "researches", topicSlug)
+  if (!existsSync(researchDir)) {
+    return { topic: topicSlug, items: [], warnings: [] }
+  }
+
+  const items: ResearchImageLead[] = []
+  const warnings: string[] = []
+  const entries = readdirSync(researchDir)
+    .filter((entry) => entry.endsWith(".md"))
+    .sort()
+
+  for (const entry of entries) {
+    const filePath = join(researchDir, entry)
+    const axis = basename(entry, ".md")
+    const sourceFile = `researches/${topicSlug}/${entry}`
+    const content = readFileSync(filePath, "utf-8")
+    const parsed = parseImageSection(topicSlug, axis, sourceFile, content)
+
+    for (const item of parsed.items) {
+      if (shouldIncludeLead(item, options)) items.push(item)
+    }
+
+    warnings.push(...parsed.warnings)
+  }
+
+  return { topic: topicSlug, items, warnings }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyber-dash-tech/revela",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "OpenCode plugin that turns AI into an HTML slide deck generator",
   "type": "module",
   "main": "./index.ts",

package/plugin.ts

@@ -47,6 +47,9 @@ import { handlePdf } from "./lib/commands/pdf"
 import { handlePptx } from "./lib/commands/pptx"
 import designsTool from "./tools/designs"
 import domainsTool from "./tools/domains"
+import mediaBatchSaveTool from "./tools/media-batch-save"
+import mediaSaveTool from "./tools/media-save"
+import researchImagesListTool from "./tools/research-images-list"
 import researchSaveTool from "./tools/research-save"
 import workspaceScanTool from "./tools/workspace-scan"
 import extractDocumentMaterialsTool from "./tools/extract-document-materials"
@@ -229,6 +232,9 @@ const server: Plugin = (async (pluginCtx) => {
     tool: {
       "revela-designs": designsTool,
       "revela-domains": domainsTool,
+      "revela-media-batch-save": mediaBatchSaveTool,
+      "revela-media-save": mediaSaveTool,
+      "revela-research-images-list": researchImagesListTool,
       "revela-research-save": researchSaveTool,
       "revela-workspace-scan": workspaceScanTool,
       "revela-extract-document-materials": extractDocumentMaterialsTool,

package/skill/SKILL.md

@@ -427,6 +427,12 @@ element selector list, and `window.getEditedHTML()` definition.
 
 ### Image Rules
 
+- When research findings contain image leads that should appear in the final deck,
+  first call `revela-research-images-list` to inspect structured candidates from
+  `researches/{slug}/*.md`. When multiple images are needed, prefer
+  `revela-media-batch-save` to save the selected candidates in one call. Use
+  `revela-media-save` for one-off cases. Then reference the returned local file
+  path in HTML. Do not use remote image URLs directly in final slides.
 - Use direct file paths (`src="assets/logo.png"`) in HTML — not base64
 - Always use the **original** file path in HTML `<img src>` for full-quality rendering
 - Never repeat the same image on multiple slides (logos: title + closing only)
@@ -493,4 +499,4 @@ The active design name is in the HTML comment at the top of this prompt:
 The active design's complete visual specification — Component Library, Layout
 Primitives, Composition Guide, and Data Visualization rules — is injected
 below after the `---` separator. This is your sole visual reference for
-generating slides.
+generating slides.

package/tools/media-batch-save.ts

@@ -0,0 +1,25 @@
+import { tool } from "@opencode-ai/plugin"
+import { batchSaveMediaAssets } from "../lib/media/batch-save"
+
+export default tool({
+  description:
+    "Save a selected batch of research-found image leads into workspace assets and update the media manifest. " +
+    "Use this after the primary agent has chosen multiple images from researches/{topic}/*.md.",
+  args: {
+    topic: tool.schema.string().describe("Topic slug shared by one presentation, e.g. 'ev-market'."),
+    items: tool.schema.array(tool.schema.object({
+      candidateId: tool.schema.string().describe("Stable candidate id returned by revela-research-images-list."),
+      description: tool.schema.string().describe("Candidate description from research findings."),
+      url: tool.schema.string().describe("Remote image URL to save."),
+      alt: tool.schema.string().optional().describe("Optional alt text."),
+      use: tool.schema.enum(["logo", "portrait", "screenshot"]).describe("Structured image use from research findings."),
+      sourceFile: tool.schema.string().optional().describe("Optional source research file path."),
+      intendedSection: tool.schema.string().optional().describe("Optional section override for this one item."),
+    })).describe("Explicitly selected image leads to save. This tool does not auto-select candidates."),
+    intendedSection: tool.schema.string().optional().describe("Optional default narrative section for all items in this batch."),
+  },
+  async execute(args, context) {
+    const workspaceDir = context.directory ?? process.cwd()
+    return JSON.stringify(await batchSaveMediaAssets(args, workspaceDir), null, 2)
+  },
+})

package/tools/media-save.ts

@@ -0,0 +1,40 @@
+import { tool } from "@opencode-ai/plugin"
+import { saveMediaAsset } from "../lib/media/save"
+
+export default tool({
+  description:
+    "Save one image asset into the workspace assets/ directory and update a media manifest. " +
+    "Supports either a sourceUrl or a sourcePath. Records both success and failure states. " +
+    "Use this when a research-found image or an existing local image should become a formal project asset.",
+  args: {
+    topic: tool.schema.string().describe("Topic slug shared by one presentation, e.g. 'ev-market'."),
+    id: tool.schema.string().describe("Stable asset id within the topic, e.g. 'tesla-logo-01'."),
+    type: tool.schema.enum(["image"]).describe("Asset type. Stage 1 only supports 'image'."),
+    purpose: tool.schema
+      .enum(["hero", "illustration", "portrait", "logo", "screenshot"])
+      .describe("Image purpose in the deck."),
+    brief: tool.schema.string().describe("One-sentence reason this image is needed."),
+    status: tool.schema
+      .enum(["success", "cannot-download", "invalid-url", "cannot-generate"])
+      .describe("'success' saves an image asset; other statuses record a failed attempt in the manifest."),
+    intendedSection: tool.schema.string().optional().describe("Optional narrative section such as 'market-overview'."),
+    sourcePath: tool.schema
+      .string()
+      .optional()
+      .describe("Optional local image path, relative to the workspace root. Preferred when both sourcePath and sourceUrl are present."),
+    sourceUrl: tool.schema
+      .string()
+      .optional()
+      .describe("Optional remote image URL to download when sourcePath is not provided."),
+    alt: tool.schema.string().optional().describe("Optional alt text for the image."),
+    notes: tool.schema.string().optional().describe("Optional usage notes for future slide generation."),
+    failureReason: tool.schema
+      .string()
+      .optional()
+      .describe("Required when status is not 'success'. Briefly explain why the image is unavailable."),
+  },
+  async execute(args, context) {
+    const workspaceDir = context.directory ?? process.cwd()
+    return JSON.stringify(await saveMediaAsset(args, workspaceDir), null, 2)
+  },
+})

package/tools/research-images-list.ts

@@ -0,0 +1,34 @@
+import { tool } from "@opencode-ai/plugin"
+import { listResearchImageLeads } from "../lib/research/image-leads"
+
+export default tool({
+  description:
+    "List structured image leads from researches/{topic}/*.md. " +
+    "Parses ## Images sections and returns candidate image records for the primary agent to review.",
+  args: {
+    topic: tool.schema.string().describe("Topic slug shared by one presentation, e.g. 'ev-market'."),
+    uses: tool.schema
+      .array(tool.schema.enum(["logo", "portrait", "screenshot", "unknown"]))
+      .optional()
+      .describe("Optional use filter, e.g. ['logo', 'portrait', 'screenshot']"),
+    axis: tool.schema
+      .array(tool.schema.string())
+      .optional()
+      .describe("Optional axis filter, e.g. ['tesla-profile', 'market-data']"),
+  },
+  async execute(args, context) {
+    const workspaceDir = context.directory ?? process.cwd()
+    const result = listResearchImageLeads(args.topic, workspaceDir, {
+      uses: args.uses,
+      axis: args.axis,
+    })
+
+    return JSON.stringify({
+      ok: true,
+      topic: result.topic,
+      count: result.items.length,
+      items: result.items,
+      warnings: result.warnings,
+    }, null, 2)
+  },
+})