@cyber-dash-tech/revela 0.10.0 → 0.12.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

@@ -14,7 +14,7 @@ export async function handleRefine(
     })
 
     await send(
-      `Opened Revela Refine for the only deck in \`decks/\`.\n` +
+      `Opened Revela Refine for the active HTML deck.\n` +
       `File: \`${result.deck.file}\`\n` +
       `${result.stateNote}\n` +
       `URL: ${result.url}\n\n` +

package/lib/commands/review.ts

@@ -6,15 +6,129 @@ export function buildReviewPrompt({
 }: {
   exists: boolean
   workspaceRoot?: string
+}): string {
+  const state = exists
+    ? `${DECKS_STATE_FILE} exists. Read it through the revela-decks tool.`
+    : `${DECKS_STATE_FILE} does not exist yet. Create or normalize it through the revela-decks tool only if there is enough workspace narrative context.`
+
+  return `Review Revela narrative readiness.
+
+Goal:
+- Use ${DECKS_STATE_FILE} as the compatibility workspace-state file, but review the canonical narrative state first: audience, belief shift, decision/action, thesis, central claims, evidence boundaries, objections, risks, and approval state.
+- Treat this as a narrative readiness review, not a deck HTML write-readiness review.
+- Do not write, patch, or directly edit ${DECKS_STATE_FILE}. Use the \`revela-decks\` tool for all state changes.
+- Call \`revela-decks\` action \`reviewNarrative\` as the authoritative deterministic readiness engine.
+- Do not call \`revela-decks\` action \`review\` here. That action is the deck/artifact gate and belongs to \`/revela deck --review\`.
+- Do not treat legacy \`writeReadiness.status\`, old review snapshots, or an existing HTML deck as narrative approval.
+- Do not write or overwrite \`decks/*.html\` during narrative review.
+- If the narrative is \`ready_for_approval\`, ask whether the user wants to approve it or revise it. Do not approve automatically.
+- Only call \`revela-decks\` action \`approveNarrative\` when the user explicitly asks to approve or override.
+
+Current state:
+- ${state}
+${workspaceRoot ? `- Current workspace root: \`${workspaceRoot}\`` : ""}
+
+Workspace boundary rules:
+- Stay strictly inside the current workspace root for every scan, glob, read, and write.
+- Do not search parent directories, home directories, or unrelated absolute directories.
+- Do not use \`~\`, \`..\`, or parent-directory traversal to discover files.
+- For Glob/file searches, use the current workspace as the search root. Do not set the search root to a parent directory or home directory.
+
+Workflow:
+1. Call \`revela-decks\` with action \`read\` to inspect the current workspace state.
+2. If ${DECKS_STATE_FILE} is missing or empty, do not invent a deck plan, slide count, design, output path, or visual style. Report the smallest narrative inputs needed, usually audience, belief-before, belief-after, decision/action, thesis, central claims, evidence availability, objections, and risks.
+3. If legacy deck state exists, let the tool-normalized canonical narrative derived from \`narrativeBrief\`, slide roles, slide content, and slide evidence be reviewed. Do not assume old deck readiness means approval.
+4. Call \`revela-decks\` action \`reviewNarrative\`. Use its returned \`status\`, \`blockers\`, \`warnings\`, \`issues\`, \`narrativeHash\`, \`approval\`, and \`nextActions\` as authoritative.
+5. If research findings have been saved but not attached or evidence-bound, report them as unattached research state, not proof.
+6. If central claims lack required evidence, report the named claim and the exact next action: attach findings, bind evidence, run targeted research, narrow unsupported scope, or rewrite the claim.
+7. If approval is missing or stale, clearly distinguish \`ready_for_approval\`, \`approved\`, and render override.
+
+Report format:
+- Start with \`Narrative readiness: <status>\`.
+- Include \`Narrative hash: <hash>\` when returned.
+- If blocked or needs research, list each blocker with issue type, claim text when available, and suggested next action.
+- If warnings exist, list them after blockers as residual risks.
+- If approval is missing, ask whether the user wants to approve the narrative or revise it.
+- If approval is stale, say the prior approval no longer matches the current narrative hash.
+- Keep deck/artifact readiness separate. If the user wants to review slide-writing readiness, tell them to run \`/revela deck --review\`.
+
+Rules:
+- Do not write or overwrite \`decks/*.html\` during narrative review.
+- Do not call \`revela-decks review\` during narrative review.
+- Do not apply evidence candidates, bind evidence, or rewrite slide text unless the user explicitly asks.
+- Do not store secrets, credentials, tokens, or sensitive personal information.
+- Do not add inferred user preferences to long-term preference state.
+
+Start now by reading ${DECKS_STATE_FILE} through \`revela-decks\`, then call \`revela-decks\` action \`reviewNarrative\`.`
+}
+
+export function buildDeckPrompt({
+  exists,
+  workspaceRoot,
+}: {
+  exists: boolean
+  workspaceRoot?: string
+}): string {
+  const state = exists
+    ? `${DECKS_STATE_FILE} exists. Read it through the revela-decks tool.`
+    : `${DECKS_STATE_FILE} does not exist yet. Do not invent a deck; initialize narrative state first with /revela init.`
+
+  return `Begin Revela deck render handoff.
+
+Goal:
+- Treat this as the explicit transition from approved narrative state to deck render planning.
+- Use the deck-render prompt mode for design, layout, component, HTML, QA, and deck artifact rules.
+- Do not write or overwrite \`decks/*.html\` until the narrative handoff and deck/artifact gate are both satisfied.
+- Do not treat legacy \`writeReadiness.status\`, old review snapshots, or existing HTML decks as narrative approval.
+- Do not bypass the deck HTML contract, review snapshot freshness, source-trace expectations, or export preflight protections.
+
+Current state:
+- ${state}
+${workspaceRoot ? `- Current workspace root: \`${workspaceRoot}\`` : ""}
+
+Workflow:
+1. Call \`revela-decks\` action \`read\`.
+2. Call \`revela-decks\` action \`reviewNarrative\` before planning deck slides.
+3. If narrative readiness is \`approved\`, continue. If it is \`ready_for_approval\`, ask the user for explicit approval before continuing. If it is blocked, stale, or needs research, stop and report the smallest next action. Do not call \`approveNarrative\` unless the user explicitly approves or requests a render override.
+4. After approval or explicit render override exists, call \`revela-decks\` action \`compileDeckPlan\`. This projects canonical narrative claims and evidence bindings into compatibility \`slides[]\` and \`slides[].evidence[]\`; it must not write HTML.
+5. If \`compileDeckPlan\` returns \`skipped\`, stop and report the reason. Do not invent slide specs manually to bypass approval.
+6. Ask for or confirm visual design only after the narrative deck plan exists. Fetch required design layouts/components with \`revela-designs read\` as needed.
+7. Update only deck/artifact metadata through \`revela-decks upsertDeck\` / \`upsertSlides\` when required by confirmed design/layout choices. Do not change canonical narrative claims unless the user asks to revise the narrative.
+8. Call \`revela-decks\` action \`review\` as the artifact gate. It computes \`writeReadiness\` and review snapshots for deck HTML writing.
+9. Write \`decks/*.html\` only if the deck/artifact gate is ready and all deck HTML contract requirements can be satisfied. If not ready, report blockers and stop.
+
+Report format before any HTML write:
+- Start with \`Deck handoff: <status>\`.
+- Include narrative readiness status and narrative hash when available.
+- Include whether \`compileDeckPlan\` compiled or skipped.
+- If deck/artifact review is blocked, list blockers separately from narrative blockers.
+- If proceeding to HTML writing, state which approved narrative hash and deck review snapshot authorized the artifact work.
+
+Rules:
+- \`compileDeckPlan\` is the canonical narrative-to-deck planning path. Do not manually invent slide specs to avoid it.
+- Deck slide specs are render-target projections. Canonical narrative remains the authority for audience, decision, claims, evidence boundaries, objections, risks, and approval.
+- Applying evidence candidates, rewriting canonical claims, or approving narratives requires explicit user instruction.
+- Do not store secrets, credentials, tokens, or sensitive personal information.
+
+Start now by reading ${DECKS_STATE_FILE}, reviewing narrative readiness, and then compiling the deck plan only if approval or explicit render override is current.`
+}
+
+export function buildDeckReviewPrompt({
+  exists,
+  workspaceRoot,
+}: {
+  exists: boolean
+  workspaceRoot?: string
 }): string {
   const state = exists
     ? `${DECKS_STATE_FILE} exists. Read it through the revela-decks tool.`
     : `${DECKS_STATE_FILE} does not exist yet. Create it through the revela-decks tool if there is enough deck context.`
 
-  return `Review Revela deck write readiness.
+  return `Review Revela deck/artifact write readiness.
 
 Goal:
 - Use ${DECKS_STATE_FILE} as the source of truth for whether the current workspace deck is ready to be written to \`decks/*.html\`.
+- Treat this as an artifact gate for deck rendering, not strategic narrative approval. Narrative readiness is reviewed by \`/revela review\`.
 - Preserve the deck spec for future sessions: every slide's content, layout, components, evidence, visuals, production status, and the 0.9 narrative compiler brief when available.
 - Do not write, patch, or directly edit ${DECKS_STATE_FILE}. Use the \`revela-decks\` tool for all state changes.
 - Let \`revela-decks\` action \`review\` compute writeReadiness; do not manually set readiness to ready.

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, "\\$&")
+}