@cyber-dash-tech/revela 0.9.0 → 0.11.0

package/lib/commands/pptx.ts

@@ -10,7 +10,10 @@
 import { existsSync, readdirSync } from "fs"
 import { relative, resolve, sep } from "path"
 import { hasDecksState, isDeckHtmlPath, readDecksState } from "../decks-state"
+import { assertDeckHtmlContractValid } from "../deck-html/contract"
 import { exportToPptx } from "../pptx/export"
+import { recordRenderedArtifact } from "../workspace-state/rendered-artifacts"
+import { resolveActiveHtmlDeckPath } from "../workspace-state/render-targets"
 
 export interface PptxArgs {
   filePath: string
@@ -20,7 +23,7 @@ export interface PptxArgs {
 export interface ResolvedPptxDeck {
   file: string
   absoluteFile: string
-  source: "decks-state" | "fallback" | "file-path"
+  source: "render-target" | "decks-state" | "fallback" | "file-path"
 }
 
 function formatSecs(ms: number): string {
@@ -46,12 +49,12 @@ export function resolvePptxDeck(workspaceRoot: string, filePath = ""): ResolvedP
 
   if (hasDecksState(root)) {
     const state = readDecksState(root)
-    const key = state.activeDeck || singleDeckKey(state.decks)
-    const outputPath = key ? state.decks[key]?.outputPath : undefined
+    const outputPath = resolveActiveHtmlDeckPath(state)
     if (outputPath && isDeckHtmlPath(outputPath)) {
       const absoluteFile = resolve(root, outputPath)
       if (existsSync(absoluteFile)) {
-        return { file: workspaceRelative(root, absoluteFile), absoluteFile, source: "decks-state" }
+        const source = state.renderTargets.some((target) => target.type === "html_deck" && target.outputPath === outputPath) ? "render-target" : "decks-state"
+        return { file: workspaceRelative(root, absoluteFile), absoluteFile, source }
       }
     }
   }
@@ -114,6 +117,7 @@ export async function handlePptx(
     const deck = resolvePptxDeck(workspaceRoot, args.filePath)
     const abs = deck.absoluteFile
 
+    assertDeckHtmlContractValid(workspaceRoot, abs)
     await send(`Exporting \`${abs}\` to PPTX...`)
     let lastSlideUpdate = 0
     let longDeckThreshold: number | null = null
@@ -141,6 +145,12 @@ export async function handlePptx(
         await send(`Editable export progress: slide ${current}/${total}`)
       },
     })
+    recordRenderedArtifact(workspaceRoot, {
+      sourceHtmlPath: deck.file,
+      outputPath: result.outputPath,
+      type: "pptx",
+      actor: "revela-pptx",
+    })
 
     await send(
       `**PPTX exported successfully**\n\n` +
@@ -159,11 +169,6 @@ export async function handlePptx(
   }
 }
 
-function singleDeckKey(decks: Record<string, unknown>): string | undefined {
-  const keys = Object.keys(decks)
-  return keys.length === 1 ? keys[0] : undefined
-}
-
 function listDeckHtmlFiles(workspaceRoot: string): string[] {
   const dir = resolve(workspaceRoot, "decks")
   if (!existsSync(dir)) return []

package/lib/commands/refine.ts

@@ -0,0 +1,26 @@
+import { openRefineDeck } from "../refine/open"
+import type { RefineMode } from "../refine/server"
+
+export async function handleRefine(
+  options: { client: any; sessionID: string; workspaceRoot: string; mode?: RefineMode },
+  send: (text: string) => Promise<void>,
+): Promise<void> {
+  try {
+    const result = openRefineDeck("", {
+      client: options.client,
+      sessionID: options.sessionID,
+      workspaceRoot: options.workspaceRoot,
+      mode: options.mode ?? "edit",
+    })
+
+    await send(
+      `Opened Revela Refine for the active HTML deck.\n` +
+      `File: \`${result.deck.file}\`\n` +
+      `${result.stateNote}\n` +
+      `URL: ${result.url}\n\n` +
+      `Use Ctrl/Cmd-click in the browser to reference deck elements. The Edit tab sends targeted change comments; the Inspect tab reviews the same selection with Source/Purpose cards and does not edit the deck.`
+    )
+  } catch (e: any) {
+    await send(`**Refine failed:** ${e.message || String(e)}`)
+  }
+}

package/lib/commands/review.ts

@@ -22,6 +22,9 @@ Goal:
 - For substantial decision decks, use the read-only Task subagent \`revela-narrative-reviewer\` for independent rubric-based critique of narrative brief and slide-plan alignment. Do not self-certify semantic narrative quality in the primary agent.
 - Treat \`revela-narrative-reviewer\` findings as advisory critique only. Do not represent them as \`revela-decks\` readiness issues, blockers, or authoritative \`writeReadiness\`.
 - Treat source trace mapping as part of evidence readiness: when research findings have been read, relevant findings should appear in slide-level \`slides[].evidence[]\` records rather than only in raw research files.
+- When \`revela-decks review\` returns \`evidenceCandidates\`, treat them as conservative binding candidates only. They are not proof that the full slide is supported, and they are not automatically applied to \`slides[].evidence[]\`. If a candidate has \`sourceKind: "researchesFallback"\`, say it was discovered from workspace \`researches/\` files that are not currently referenced by \`researchPlan\`.
+- When an evidence candidate includes \`evidenceDraft\`, report it as a proposed slide evidence record with its \`candidateId\`; it still requires explicit user/agent confirmation before calling \`revela-decks\` action \`applyEvidenceCandidates\`. Also report \`unsupportedScope\` and \`recommendedRewrite\` so partial evidence is not stretched to future-state claims.
+- When a missing-evidence issue has \`evidenceCandidateSearch\`, use it to explain search coverage: which \`researchPlan\` findings were searched, which fallback \`researches/**/*.md\` files were searched, and any near misses that were below binding threshold.
 
 Current state:
 - ${state}
@@ -36,7 +39,7 @@ Workspace boundary rules:
 Workflow:
 1. Call \`revela-decks\` with action \`read\` for the current workspace deck.
 2. If no current deck exists but the conversation contains enough deck context, call \`revela-decks\` action \`upsertDeck\` with goal, outputPath, theme, requiredInputs, researchPlan, and narrativeBrief if the story intent is clear. Do not invent or ask for a deck key; the tool uses the workspace folder name internally.
-3. If \`researchPlan[].status\` is \`done\` or \`read\` and \`researchPlan[].findingsFile\` exists, verify that evidence-sensitive slide claims are backed by compact \`slides[].evidence[]\` records that reference the relevant findings file or source material where known.
+3. If \`researchPlan[].status\` is \`done\` or \`read\` and \`researchPlan[].findingsFile\` exists, verify that evidence-sensitive slide claims are backed by compact \`slides[].evidence[]\` records that reference the relevant findings file or source material where known. The review tool may surface conservative \`evidenceCandidates\` for missing evidence by matching slide text against those findings files, and may fall back to bounded workspace \`researches/**/*.md\` discovery when the research plan has no matching findings file; report these as candidate bindings, not as already-bound evidence.
 4. If a user-confirmed slide plan is available, call \`revela-decks\` action \`upsertSlides\` with every slide's title, purpose, narrativeRole, layout, components, structured content, evidence, visuals, and status. Use only lightweight narrativeRole values that are clear from the plan: \`context\`, \`tension\`, \`evidence\`, \`recommendation\`, \`risk\`, \`ask\`, \`appendix\`, or \`close\`.
 5. Prefer evidence records with \`findingsFile\`, \`sourcePath\`, \`location\`, \`quote\`, \`url\`, \`caveat\`, \`extractedTextPath\`, or \`extractedManifestPath\` when those fields are known from research files or extracted workspace materials.
 6. Do not invent quotes, page references, locations, URLs, caveats, or extraction paths. If source trace is missing, preserve the blocker or warning and report exactly what trace is needed.
@@ -44,7 +47,7 @@ Workflow:
 8. For substantial decision decks, preserve a compact \`narrativeBrief\` through \`upsertDeck\` when the conversation or confirmed plan supports it. Do not invent stakeholder beliefs, objections, or risks; leave gaps visible if unknown.
 9. For substantial decision decks, launch the Task subagent with \`subagent_type: "revela-narrative-reviewer"\` after deck/slides are up to date. Ask it to read the current \`DECKS.json\`, run only its fixed rubric, use stable finding IDs, return \`Findings: none\` when all checks pass, and avoid optional pre-write improvements. Do not ask it to write state, call \`revela-decks review\`, or produce HTML.
 10. Call \`revela-decks\` action \`review\`. The tool computes and writes \`writeReadiness\` plus structured readiness issues for the current workspace deck.
-11. Briefly report whether the deck is ready. If blocked, list the exact blockers returned by the tool. If warnings exist, list them after blockers as residual risks; separate evidence/source warnings from narrative warnings when possible. If the reviewer returned findings, include them in a separate \`Narrative reviewer notes\` section and label them advisory.
+11. Briefly report whether the deck is ready. If blocked, list the exact blockers returned by the tool. If warnings exist, list them after blockers as residual risks; separate evidence/source warnings from narrative warnings when possible. If the review result includes \`evidenceCandidates\`, add a separate \`Candidate evidence bindings\` section with candidateId, slide index/title, supported claim scope, sourceKind, findingsFile/sourcePath, quote/snippet, caveat, evidenceDraft summary, unsupportedScope, and recommendedRewrite. Tell the user they may explicitly ask to apply selected candidate IDs; do not apply them during review. If candidates are absent but \`evidenceCandidateSearch\` is present, briefly report searched file counts and the best near misses so the user can tell whether review failed to search or searched but did not find a bindable match. If the reviewer returned findings, include them in a separate \`Narrative reviewer notes\` section and label them advisory.
 
 Minimum conditions for \`ready\`:
 - Topic, audience, slide count, language, and visual style/design are decided.
@@ -68,6 +71,9 @@ Report format:
 - Do not invent evidence or silently downgrade blockers. Use the tool result as authoritative.
 - Do not convert \`revela-narrative-reviewer\` advisory findings into tool readiness issues. Keep them separate from \`revela-decks review\` blockers and warnings, and preserve the reviewer's stable finding IDs when reporting them.
 - When reporting weak evidence, say whether the missing trace is \`findingsFile\`, \`sourcePath\`, \`location\`, \`quote\`, \`url\`, or \`caveat\` if that is clear from the reviewed materials.
+- When reporting candidate evidence bindings, distinguish partial support from full-slide support. Never say a candidate supports unrelated future-state, recommendation, roadmap, or product-vision claims unless the candidate explicitly supports those claims.
+- Treat \`evidenceDraft\` as a proposed record, not a mutation. Do not call \`upsertSlides\` to bind it. Only call \`revela-decks\` action \`applyEvidenceCandidates\` with explicit \`candidateIds\` if the user asks to apply candidate bindings.
+- When reporting candidate search diagnostics, do not present near misses as evidence. Say they are below binding threshold and use them only to explain why no candidate was returned.
 
 Rules:
 - Do not write or overwrite \`decks/*.html\` during review.

package/lib/deck-html/contract.ts

@@ -0,0 +1,252 @@
+import { existsSync, readFileSync } from "fs"
+import { relative, resolve, sep } from "path"
+import { hasDecksState, readDecksState, type DeckSpec } from "../decks-state"
+import { resolveActiveHtmlDeckPath, normalizeWorkspacePath } from "../workspace-state/render-targets"
+
+export type DeckHtmlContractStatus = "valid" | "invalid" | "skipped"
+
+export type DeckHtmlContractIssueType =
+  | "file_not_found"
+  | "no_matching_deck_spec"
+  | "missing_slide_section"
+  | "slide_count_mismatch"
+  | "missing_data_slide_index"
+  | "invalid_data_slide_index"
+  | "duplicate_data_slide_index"
+  | "slide_index_mismatch"
+  | "legacy_data_index_noncanonical"
+
+export interface DeckHtmlContractIssue {
+  type: DeckHtmlContractIssueType
+  severity: "error" | "warning"
+  message: string
+  slidePosition?: number
+  expectedIndex?: number
+  actualIndex?: number
+}
+
+export interface DeckHtmlContractReport {
+  status: DeckHtmlContractStatus
+  ok: boolean
+  workspaceRoot: string
+  filePath: string
+  deckSlug?: string
+  activeHtmlPath?: string
+  expectedIndexes: number[]
+  actualIndexes: number[]
+  issues: DeckHtmlContractIssue[]
+  warnings: DeckHtmlContractIssue[]
+}
+
+interface SlideSectionAttrs {
+  position: number
+  dataSlideIndex?: string
+  dataIndex?: string
+}
+
+export function validateDeckHtmlContract(workspaceRoot: string, filePath: string): DeckHtmlContractReport {
+  const root = resolve(workspaceRoot)
+  const absoluteFile = resolve(root, filePath)
+  const relativeFile = workspaceRelative(root, absoluteFile)
+  const base: Omit<DeckHtmlContractReport, "status" | "ok"> = {
+    workspaceRoot: root,
+    filePath: relativeFile,
+    expectedIndexes: [],
+    actualIndexes: [],
+    issues: [],
+    warnings: [],
+  }
+
+  if (!hasDecksState(root)) return skipped(base, "No DECKS.json exists; deck HTML contract validation is skipped.")
+
+  const state = readDecksState(root)
+  const activeHtmlPath = resolveActiveHtmlDeckPath(state)
+  const activeKey = state.activeDeck || singleDeckKey(state.decks)
+  const deck = activeKey ? state.decks[activeKey] : undefined
+  const normalizedActive = normalizeWorkspacePath(activeHtmlPath ?? "")
+  const normalizedTarget = normalizeWorkspacePath(relativeFile)
+
+  base.activeHtmlPath = normalizedActive || undefined
+  base.deckSlug = deck?.slug
+
+  if (!deck || !normalizedActive || normalizedActive !== normalizedTarget) {
+    return skipped(base, `No matching active deck spec exists for ${relativeFile}; deck HTML contract validation is skipped.`)
+  }
+
+  if (!existsSync(absoluteFile)) {
+    base.issues.push({
+      type: "file_not_found",
+      severity: "error",
+      message: `Deck HTML file not found: ${relativeFile}`,
+    })
+    return finalize(base)
+  }
+
+  const html = readFileSync(absoluteFile, "utf-8")
+  const sections = extractSlideSections(html)
+  base.expectedIndexes = expectedSlideIndexes(deck)
+
+  if (sections.length === 0) {
+    base.issues.push({
+      type: "missing_slide_section",
+      severity: "error",
+      message: "Deck HTML must contain one <section class=\"slide\"> element per slide spec.",
+    })
+    return finalize(base)
+  }
+
+  if (sections.length !== base.expectedIndexes.length) {
+    base.issues.push({
+      type: "slide_count_mismatch",
+      severity: "error",
+      message: `Deck HTML has ${sections.length} slide sections, but DECKS.json expects ${base.expectedIndexes.length}.`,
+    })
+  }
+
+  const seen = new Set<number>()
+  sections.forEach((section, offset) => {
+    const expectedIndex = base.expectedIndexes[offset]
+    if (section.dataIndex !== undefined) {
+      base.warnings.push({
+        type: "legacy_data_index_noncanonical",
+        severity: "warning",
+        message: `Slide ${section.position} has legacy data-index; use data-slide-index as the canonical slide identity.`,
+        slidePosition: section.position,
+      })
+    }
+
+    if (section.dataSlideIndex === undefined) {
+      base.issues.push({
+        type: "missing_data_slide_index",
+        severity: "error",
+        message: `Slide ${section.position} is missing data-slide-index.`,
+        slidePosition: section.position,
+        expectedIndex,
+      })
+      return
+    }
+
+    const actualIndex = Number(section.dataSlideIndex)
+    if (!Number.isInteger(actualIndex) || actualIndex < 1 || String(actualIndex) !== section.dataSlideIndex.trim()) {
+      base.issues.push({
+        type: "invalid_data_slide_index",
+        severity: "error",
+        message: `Slide ${section.position} has invalid data-slide-index=${JSON.stringify(section.dataSlideIndex)}; expected a positive 1-based integer.`,
+        slidePosition: section.position,
+        expectedIndex,
+      })
+      return
+    }
+
+    base.actualIndexes.push(actualIndex)
+    if (seen.has(actualIndex)) {
+      base.issues.push({
+        type: "duplicate_data_slide_index",
+        severity: "error",
+        message: `Slide ${section.position} repeats data-slide-index=${actualIndex}.`,
+        slidePosition: section.position,
+        actualIndex,
+      })
+    }
+    seen.add(actualIndex)
+
+    if (expectedIndex !== undefined && actualIndex !== expectedIndex) {
+      base.issues.push({
+        type: "slide_index_mismatch",
+        severity: "error",
+        message: `Slide ${section.position} has data-slide-index=${actualIndex}, but DECKS.json expects ${expectedIndex}.`,
+        slidePosition: section.position,
+        expectedIndex,
+        actualIndex,
+      })
+    }
+  })
+
+  return finalize(base)
+}
+
+export function assertDeckHtmlContractValid(workspaceRoot: string, filePath: string): void {
+  const report = validateDeckHtmlContract(workspaceRoot, filePath)
+  if (report.status !== "invalid") return
+  throw new Error(
+    "Deck HTML contract validation failed. Fix slide identity before inspection or export.\n\n" +
+    formatDeckHtmlContractReport(report)
+  )
+}
+
+export function formatDeckHtmlContractReport(report: DeckHtmlContractReport): string {
+  const lines = [
+    `Status: ${report.status}`,
+    `File: ${report.filePath}`,
+  ]
+  if (report.deckSlug) lines.push(`Deck: ${report.deckSlug}`)
+  if (report.activeHtmlPath) lines.push(`Active HTML target: ${report.activeHtmlPath}`)
+  if (report.expectedIndexes.length > 0) lines.push(`Expected slide indexes: ${report.expectedIndexes.join(", ")}`)
+  if (report.actualIndexes.length > 0) lines.push(`Actual slide indexes: ${report.actualIndexes.join(", ")}`)
+
+  if (report.issues.length > 0) {
+    lines.push("", "Errors:")
+    for (const issue of report.issues) lines.push(`- ${issue.message}`)
+  }
+  if (report.warnings.length > 0) {
+    lines.push("", "Warnings:")
+    for (const warning of report.warnings) lines.push(`- ${warning.message}`)
+  }
+  if (report.status === "skipped" && report.warnings.length > 0) {
+    lines.push("", "Note: skipped reports do not block standalone HTML files.")
+  }
+
+  return lines.join("\n")
+}
+
+function extractSlideSections(html: string): SlideSectionAttrs[] {
+  const sections: SlideSectionAttrs[] = []
+  const sectionTagPattern = /<section\b([^>]*)>/gi
+  let match: RegExpExecArray | null
+  while ((match = sectionTagPattern.exec(html))) {
+    const attrs = match[1] ?? ""
+    if (!/\bclass\s*=\s*(["'])[^"']*\bslide\b[^"']*\1/i.test(attrs)) continue
+    sections.push({
+      position: sections.length + 1,
+      dataSlideIndex: readAttr(attrs, "data-slide-index"),
+      dataIndex: readAttr(attrs, "data-index"),
+    })
+  }
+  return sections
+}
+
+function readAttr(attrs: string, name: string): string | undefined {
+  const pattern = new RegExp(`\\b${escapeRegExp(name)}\\s*=\\s*(["'])(.*?)\\1`, "i")
+  return pattern.exec(attrs)?.[2]
+}
+
+function expectedSlideIndexes(deck: DeckSpec): number[] {
+  return deck.slides.map((slide) => slide.index)
+}
+
+function finalize(base: Omit<DeckHtmlContractReport, "status" | "ok">): DeckHtmlContractReport {
+  const status: DeckHtmlContractStatus = base.issues.length > 0 ? "invalid" : "valid"
+  return { ...base, status, ok: status === "valid" }
+}
+
+function skipped(base: Omit<DeckHtmlContractReport, "status" | "ok">, message: string): DeckHtmlContractReport {
+  return {
+    ...base,
+    status: "skipped",
+    ok: true,
+    warnings: [{ type: "no_matching_deck_spec", severity: "warning", message }],
+  }
+}
+
+function singleDeckKey(decks: Record<string, DeckSpec>): string | undefined {
+  const keys = Object.keys(decks)
+  return keys.length === 1 ? keys[0] : undefined
+}
+
+function workspaceRelative(root: string, target: string): string {
+  return relative(root, target).split(sep).join("/")
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
+}