@cyber-dash-tech/revela 0.10.0 → 0.11.0

package/plugin.ts

@@ -48,6 +48,7 @@ import { buildPptxNotesPrompt, handlePptx, parsePptxArgs, resolvePptxDeck } from
 import { handleEdit } from "./lib/commands/edit"
 import { handleInspect } from "./lib/commands/inspect"
 import { handleRefine } from "./lib/commands/refine"
+import { formatDeckHtmlContractReport, validateDeckHtmlContract } from "./lib/deck-html/contract"
 import { ensureEditableDeckOpenForChange } from "./lib/edit/open"
 import { hasLiveEditorSessionForFile } from "./lib/edit/server"
 import { handleDesignsPreview } from "./lib/commands/designs-preview"
@@ -177,6 +178,27 @@ const server: Plugin = (async (pluginCtx) => {
     }
   }
 
+  async function appendDeckHtmlContractReport(filePath: string, output: any): Promise<void> {
+    if (!isDeckHtmlPath(filePath)) return
+
+    try {
+      const report = validateDeckHtmlContract(workspaceRoot, filePath)
+      if (report.status === "valid" || report.status === "skipped") return
+
+      appendToolResult(
+        output,
+        "---\n\n**[revela deck HTML contract]** Slide identity check failed:\n\n" +
+        formatDeckHtmlContractReport(report) +
+        "\n\nFix every `<section class=\"slide\">` to use the matching 1-based `data-slide-index` from DECKS.json before inspection or export."
+      )
+    } catch (e) {
+      childLog("deck-contract").warn("deck HTML contract report failed", {
+        filePath,
+        error: e instanceof Error ? e.message : String(e),
+      })
+    }
+  }
+
   function extractSessionID(input: any): string {
     return input?.sessionID ?? input?.session?.id ?? input?.context?.sessionID ?? ""
   }
@@ -423,7 +445,7 @@ const server: Plugin = (async (pluginCtx) => {
         throw new Error("__REVELA_DOMAINS_RM_HANDLED__")
       }
       if (sub === "pdf") {
-        await handlePdf(param, send)
+        await handlePdf(param, send, workspaceRoot)
         throw new Error("__REVELA_PDF_HANDLED__")
       }
       if (sub === "pptx") {
@@ -742,6 +764,7 @@ Next step: use \`revela-decks\` or \`/revela review\` to update ${DECKS_STATE_FI
           return
         }
         await appendComplianceReport(filePath, output)
+        await appendDeckHtmlContractReport(filePath, output)
         ensureEditorOpenAfterDeckChange(filePath, extractSessionID(input))
         return
       }
@@ -763,6 +786,7 @@ Next step: use \`revela-decks\` or \`/revela review\` to update ${DECKS_STATE_FI
         const targets = patchText ? extractDeckHtmlTargetsFromPatch(patchText) : []
         for (const target of targets) {
           await appendComplianceReport(target, output)
+          await appendDeckHtmlContractReport(target, output)
           ensureEditorOpenAfterDeckChange(target, extractSessionID(input))
         }
         return
@@ -771,6 +795,7 @@ Next step: use \`revela-decks\` or \`/revela review\` to update ${DECKS_STATE_FI
       if (input.tool === "edit") {
         const filePath = extractEditFilePath(input.args)
         await appendComplianceReport(filePath, output)
+        await appendDeckHtmlContractReport(filePath, output)
         ensureEditorOpenAfterDeckChange(filePath, extractSessionID(input))
         return
       }

package/tools/decks.ts

@@ -1,6 +1,5 @@
 import { tool } from "@opencode-ai/plugin"
 import {
-  applyEvidenceCandidates,
   createDeckSpec,
   DECKS_STATE_FILE,
   normalizeWorkspaceDeckState,
@@ -18,6 +17,10 @@ import {
   type SlideSpec,
 } from "../lib/decks-state"
 import { upsertSourceMaterial } from "../lib/source-materials"
+import { recordWorkspaceAction } from "../lib/workspace-state/actions"
+import { applyEvidenceBindings } from "../lib/workspace-state/evidence-status"
+import { attachResearchFindings } from "../lib/workspace-state/research-attachments"
+import { activeReviewTargetId, latestReviewSnapshotForTarget } from "../lib/workspace-state/review-snapshots"
 
 export default tool({
   description:
@@ -26,7 +29,7 @@ export default tool({
     "It stores active deck specs, per-slide content/layout/components, and computes write readiness.",
   args: {
     action: tool.schema
-      .enum(["read", "init", "upsertDeck", "upsertSlides", "review", "applyEvidenceCandidates", "remember"])
+      .enum(["read", "init", "upsertDeck", "upsertSlides", "review", "applyEvidenceCandidates", "attachResearchFindings", "remember"])
       .describe("Action to perform on DECKS.json."),
     summary: tool.schema.boolean().optional().describe("For read: return a compact summary instead of full state."),
     goal: tool.schema.string().optional().describe("For upsertDeck: deck goal."),
@@ -118,6 +121,9 @@ export default tool({
       notes: tool.schema.string().optional().describe("Implementation notes for this slide."),
     })).optional().describe("For upsertSlides: complete or partial slide specs."),
     candidateIds: tool.schema.array(tool.schema.string()).optional().describe("For applyEvidenceCandidates: candidate IDs returned by revela-decks review to explicitly bind proposed evidenceDraft records into slide evidence."),
+    findingsFile: tool.schema.string().optional().describe("For attachResearchFindings: workspace-relative researches/{topic}/{axis}.md file to attach to researchPlan."),
+    researchAxis: tool.schema.string().optional().describe("For attachResearchFindings: researchPlan axis to attach the findings file to. Required when filename matching would be ambiguous."),
+    researchStatus: tool.schema.enum(["done", "read"]).optional().describe("For attachResearchFindings: optional explicit status to set on the matched research axis."),
   },
   async execute(args, context) {
     try {
@@ -126,8 +132,20 @@ export default tool({
       const defaultSlug = workspaceDeckSlug(workspaceRoot)
 
       if (args.action === "init") {
+        const discovered: SourceMaterial[] = []
         for (const material of (args.sourceMaterials ?? []) as SourceMaterial[]) {
           upsertSourceMaterial(state, material, material.status ?? "discovered")
+          discovered.push(material)
+        }
+        if (discovered.length > 0) {
+          recordWorkspaceAction(state, {
+            type: "source.discovered",
+            actor: "revela-decks",
+            inputs: { count: discovered.length },
+            outputs: { paths: discovered.map((material) => material.path), statuses: discovered.map((material) => material.status ?? "discovered") },
+            summary: `Registered ${discovered.length} discovered source material${discovered.length === 1 ? "" : "s"}.`,
+            nodeIds: discovered.map((material) => `source:${material.path}`),
+          })
         }
         writeDecksState(workspaceRoot, state)
         return JSON.stringify({ ok: true, path: DECKS_STATE_FILE, state }, null, 2)
@@ -178,6 +196,28 @@ export default tool({
 
       if (args.action === "review") {
         const reviewed = reviewDeckState(state, undefined, { workspaceRoot })
+        const targetId = activeReviewTargetId(reviewed.state)
+        const snapshot = latestReviewSnapshotForTarget(reviewed.state, targetId)
+        recordWorkspaceAction(reviewed.state, {
+          type: "review.performed",
+          actor: "revela-decks",
+          inputs: { activeDeck: state.activeDeck },
+          outputs: {
+            slug: reviewed.result.slug,
+            status: reviewed.result.status,
+            ready: reviewed.result.ready,
+            blockerCount: reviewed.result.blockers.length,
+            warningCount: reviewed.result.warnings.length,
+            issueCount: reviewed.result.issues.length,
+            evidenceCandidateCount: reviewed.result.evidenceCandidates?.length ?? 0,
+            snapshotId: snapshot?.id,
+            inputHash: snapshot?.inputHash,
+            targetId: snapshot?.targetId,
+          },
+          status: "success",
+          summary: `Reviewed deck readiness: ${reviewed.result.ready ? "ready" : "blocked"}.`,
+          nodeIds: [`artifact:${reviewed.state.decks[reviewed.result.slug]?.outputPath ?? reviewed.result.slug}`, ...(snapshot ? [snapshot.id] : [])],
+        })
         writeDecksState(workspaceRoot, reviewed.state)
         return JSON.stringify({ ok: true, path: DECKS_STATE_FILE, result: reviewed.result }, null, 2)
       }
@@ -185,9 +225,18 @@ export default tool({
       if (args.action === "applyEvidenceCandidates") {
         const candidateIds = args.candidateIds ?? []
         if (candidateIds.length === 0) return JSON.stringify({ ok: false, error: "candidateIds are required for applyEvidenceCandidates" })
-        const applied = applyEvidenceCandidates(state, candidateIds, { workspaceRoot })
-        writeDecksState(workspaceRoot, applied.state)
-        return JSON.stringify({ ok: true, path: DECKS_STATE_FILE, result: applied.result }, null, 2)
+        const result = applyEvidenceBindings(workspaceRoot, candidateIds)
+        return JSON.stringify({ ok: true, path: DECKS_STATE_FILE, result }, null, 2)
+      }
+
+      if (args.action === "attachResearchFindings") {
+        if (!args.findingsFile?.trim()) return JSON.stringify({ ok: false, error: "findingsFile is required for attachResearchFindings" })
+        const result = attachResearchFindings(workspaceRoot, {
+          findingsFile: args.findingsFile,
+          researchAxis: args.researchAxis,
+          status: args.researchStatus,
+        })
+        return JSON.stringify({ ok: true, path: DECKS_STATE_FILE, result }, null, 2)
       }
 
       if (args.action === "remember") {

package/tools/pdf.ts

@@ -9,6 +9,7 @@ import { existsSync } from "fs"
 import { resolve } from "path"
 import { exportToPdf } from "../lib/pdf/export"
 import { assertExportQAPassed } from "../lib/qa/export-gate"
+import { recordRenderedArtifact, workspaceRelative } from "../lib/workspace-state/rendered-artifacts"
 
 export default tool({
   description:
@@ -35,8 +36,15 @@ export default tool({
     }
 
     try {
-      await assertExportQAPassed(filePath)
+      const root = directory || process.cwd()
+      await assertExportQAPassed(filePath, { workspaceRoot: root })
       const result = await exportToPdf(filePath)
+      recordRenderedArtifact(root, {
+        sourceHtmlPath: workspaceRelative(resolve(root), filePath),
+        outputPath: result.outputPath,
+        type: "pdf",
+        actor: "revela-pdf",
+      })
       return JSON.stringify({ ok: true, ...result }, null, 2)
     } catch (e: any) {
       return JSON.stringify({ ok: false, error: e?.message ?? String(e) })

package/tools/pptx.ts

@@ -7,7 +7,9 @@
 import { tool } from "@opencode-ai/plugin"
 import { existsSync } from "fs"
 import { resolve } from "path"
+import { assertDeckHtmlContractValid } from "../lib/deck-html/contract"
 import { exportToPptx } from "../lib/pptx/export"
+import { recordRenderedArtifact, workspaceRelative } from "../lib/workspace-state/rendered-artifacts"
 
 export default tool({
   description:
@@ -42,12 +44,20 @@ export default tool({
     const progress: string[] = []
 
     try {
+      const root = directory || process.cwd()
+      assertDeckHtmlContractValid(root, filePath)
       const result = await exportToPptx(filePath, {
         speakerNotes: normalizeSpeakerNotes(speakerNotes),
         onProgress: (event) => {
           progress.push(event.message)
         },
       })
+      recordRenderedArtifact(root, {
+        sourceHtmlPath: workspaceRelative(resolve(root), filePath),
+        outputPath: result.outputPath,
+        type: "pptx",
+        actor: "revela-pptx",
+      })
       return JSON.stringify({ ok: true, ...result, progress }, null, 2)
     } catch (e: any) {
       return JSON.stringify({ ok: false, error: e?.message ?? String(e), progress })

package/tools/research-save.ts

@@ -1,6 +1,8 @@
 import { tool } from "@opencode-ai/plugin"
 import { mkdirSync, writeFileSync } from "fs"
 import { join } from "path"
+import { hasDecksState, readDecksState, writeDecksState } from "../lib/decks-state"
+import { recordWorkspaceAction } from "../lib/workspace-state/actions"
 
 /**
  * Format today's date as YYYY-MM-DD
@@ -88,6 +90,19 @@ export default tool({
 
       writeFileSync(filePath, fileContent, "utf-8")
 
+      if (hasDecksState(workspaceDir)) {
+        const state = readDecksState(workspaceDir)
+        recordWorkspaceAction(state, {
+          type: "research.findings_saved",
+          actor: "revela-research-save",
+          inputs: { topic: topicKey, axis: fileKey, sourceCount: args.sources?.length ?? 0 },
+          outputs: { path: relPath, sources: args.sources ?? [] },
+          summary: `Saved research findings for ${topicKey}/${fileKey}.`,
+          nodeIds: [`finding:${relPath}`],
+        })
+        writeDecksState(workspaceDir, state)
+      }
+
       return JSON.stringify({ ok: true, path: relPath })
     } catch (e: any) {
       return JSON.stringify({ error: e.message || String(e) })

package/tools/workspace-scan.ts

@@ -3,6 +3,8 @@ import { readdirSync, statSync, existsSync } from "fs"
 import { join, relative, extname, resolve, sep, isAbsolute } from "path"
 import { sourceMaterialMetadata } from "../lib/source-materials"
 import type { SourceMaterial } from "../lib/decks-state"
+import { hasDecksState, readDecksState, writeDecksState } from "../lib/decks-state"
+import { recordWorkspaceAction } from "../lib/workspace-state/actions"
 
 const DOC_EXTENSIONS = new Set([
   ".pdf", ".docx", ".doc", ".xlsx", ".xls",
@@ -145,6 +147,19 @@ export default tool({
       const results: FileEntry[] = []
       scanDir(scanRoot, workspaceDir, results, maxDepth, 0)
 
+      if (hasDecksState(workspaceDir)) {
+        const state = readDecksState(workspaceDir)
+        recordWorkspaceAction(state, {
+          type: "workspace.scanned",
+          actor: "revela-workspace-scan",
+          inputs: { path: args.path, maxDepth },
+          outputs: { found: results.length, paths: results.map((file) => file.path) },
+          summary: `Scanned workspace documents and found ${results.length} file${results.length === 1 ? "" : "s"}.`,
+          nodeIds: results.map((file) => `source:${file.sourceMaterial.path}`),
+        })
+        writeDecksState(workspaceDir, state)
+      }
+
       if (results.length === 0) {
         return JSON.stringify({
           found: 0,