@cyber-dash-tech/revela 0.17.5 → 0.17.6

package/lib/commands/review.ts

@@ -93,11 +93,12 @@ Workflow:
 6. If target slide count, audience, language, output purpose, or visual style is unclear, ask the user for the smallest needed confirmation before writing the plan.
 7. Write \`deck-plan/index.md\` and one file per planned slide under \`deck-plan/slides/*.md\` from the planning packet and requirements. The index must identify the chapter structure first: 3-5 chapter headings, each chapter's slide range, and which non-structural slides belong to each chapter. Each slide file must include frontmatter with positive 1-based \`slideIndex\` and \`## Narrative Links\` using plain wikilinks to canonical claim/evidence/risk/objection/gap ids. Include a low-fidelity ASCII/text layout sketch for every slide; do not generate visual images or HTML mockups.
 8. Stop after presenting the plan unless the user already asked to proceed. Ask whether to continue, revise the plan, or run more research. Do not require an Approval block or \`confirmDeckPlan\` gate; \`confirmDeckPlan\` is compatibility/provenance only.
-9. Ask for or confirm visual design only after the narrative deck plan exists. Fetch required design layouts/components with \`revela-designs read\` as needed.
-10. Do not update cached \`DECKS.json\` slide specs for plan authoring. Use \`deck-plan/\` files and artifact files as the execution surface.
-11. Call \`revela-decks\` action \`readDeckPlan\` before artifact review or HTML writing; use it to inspect the current deck-plan projection without regenerating it. Treat stale hashes, missing links, or incomplete coverage as advisory diagnostics unless the user asks to stop.
-12. Run artifact diagnostics when useful, but do not treat \`writeReadiness\`, cached slide specs, unconfirmed plans, missing research, or stale coverage as workflow blockers.
-13. Write \`decks/*.html\` when the user chooses to proceed and all deck HTML contract requirements can be satisfied. Generate the artifact chapter by chapter instead of drafting all content slides in one broad pass. Partial decks are allowed during chapter-by-chapter authoring when written slide sections have unique, increasing 1-based \`data-slide-index\` values and valid canvases; do not pad missing planned chapters with filler to match cached \`DECKS.json.slides[]\` length. Keep the HTML file valid after every write, preserve already-written slides, and update one chapter's slide sections at a time.
+9. Ask for or confirm visual design only after the narrative deck plan exists. For a new deck HTML file, call \`revela-deck-foundation\` first to create the active-design foundation shell; it must not create narrative slide content, choose layouts/components, or read/write \`${DECKS_STATE_FILE}\`.
+10. Fetch active design rules plus required layouts/components with \`revela-designs read\` as needed before patching slides into the foundation shell. Fetch chart rules before ECharts.
+11. Do not update cached \`DECKS.json\` slide specs for plan authoring. Use \`deck-plan/\` files and artifact files as the execution surface.
+12. Call \`revela-decks\` action \`readDeckPlan\` before artifact review or HTML writing; use it to inspect the current deck-plan projection without regenerating it. Treat stale hashes, missing links, or incomplete coverage as advisory diagnostics unless the user asks to stop.
+13. Run artifact diagnostics when useful, but do not treat \`writeReadiness\`, cached slide specs, unconfirmed plans, missing research, or stale coverage as workflow blockers.
+14. Write \`decks/*.html\` when the user chooses to proceed and all deck HTML contract requirements can be satisfied. For new files, patch slide sections between the \`revela-slides\` markers created by \`revela-deck-foundation\`. Generate the artifact chapter by chapter instead of drafting all content slides in one broad pass. Partial decks are allowed during chapter-by-chapter authoring when written slide sections have unique, increasing 1-based \`data-slide-index\` values and valid canvases; do not pad missing planned chapters with filler to match cached \`DECKS.json.slides[]\` length. Keep the HTML file valid after every write, preserve already-written slides, and update one chapter's slide sections at a time.
 15. For each chapter, make every content slide carry a distinct claim, evidence item, comparison, risk, or action. If a chapter lacks enough substance for its allocated slides, merge weak slides or reduce the slide count instead of creating sparse filler.
 16. After each HTML write, the system automatically runs artifact QA before opening Review. If post-write artifact QA reports hard errors, fix them and let QA run again. Review opens only after hard errors pass. Density warnings about thin claim/evidence substance should be reported and improved when useful, but they do not block Review.
 
@@ -142,6 +143,7 @@ Report format before any HTML write:
 - Start with \`Deck handoff: <status>\`.
 - Include which deck-plan projection and narrative hash are guiding artifact work.
 - State that \`revela-decks readDeckPlan\` was called and the current \`deck-plan/\` Chapter Writing Batches are being followed.
+- For new HTML files, state that \`revela-deck-foundation\` created the foundation shell and identify the output path/design before slide content is patched.
 - Include the chapter currently being generated and confirm already-written slides are being preserved.
 - If technical artifact checks cannot be satisfied, list those blockers separately from narrative/deck-plan diagnostics.
 - After writing HTML, read the appended \`Artifact QA\` report from the tool output. If it failed, fix hard errors before considering the deck ready for Review.
@@ -149,6 +151,7 @@ Report format before any HTML write:
 Rules:
 - \`compileDeckPlan\` prepares the canonical narrative claim/evidence packet and deck-plan requirements. The LLM authors \`deck-plan/index.md\` and \`deck-plan/slides/*.md\` from that packet and asks the user for page count, audience, language, output purpose, or visual style when unclear.
 - \`deck-plan/\` is the execution blueprint for HTML generation when present. It must be read before writing HTML and followed chapter by chapter; \`DECKS.json.slides[]\` is compatibility/cache data, not the HTML slide-count authority.
+- \`revela-deck-foundation\` is the file-native foundation helper for new deck shells. Use it before adding slides to a new \`decks/*.html\` file; do not use \`DECKS.json\` or \`revela-decks\` to create the shell.
 - Visual intent is part of the deck-plan projection. During HTML generation, satisfy the planned component/visual brief using fetched design components; do not collapse planned visuals into prose-only bullets.
 - Cached deck slide specs in \`DECKS.json\` are legacy projections only. Canonical narrative remains the authority for audience, decision, claims, evidence boundaries, objections, and risks.
 - Cover, Table of Contents, and Closing are mandatory deck structure. TOC chapter headings must match the chapter grouping used for generation.

package/lib/deck-html/foundation.ts

@@ -0,0 +1,190 @@
+import { existsSync, mkdirSync, writeFileSync } from "fs"
+import { dirname, isAbsolute, normalize, resolve } from "path"
+import { activeDesign, getDesignSection } from "../design/designs"
+
+export type DeckFoundationMode = "create" | "repair"
+export type DeckFoundationStatus = "created" | "updated"
+
+export interface CreateDeckFoundationInput {
+  workspaceRoot: string
+  outputPath: string
+  title: string
+  language: string
+  designName?: string
+  mode?: DeckFoundationMode
+  overwrite?: boolean
+}
+
+export interface CreateDeckFoundationResult {
+  ok: true
+  outputPath: string
+  design: string
+  includedSections: string[]
+  status: DeckFoundationStatus
+  next: string[]
+}
+
+interface FoundationParts {
+  fontLinks: string[]
+  cssBlocks: string[]
+  scriptBlocks: string[]
+}
+
+const SLIDES_START = "<!-- revela-slides:start -->"
+const SLIDES_END = "<!-- revela-slides:end -->"
+
+export function createDeckFoundation(input: CreateDeckFoundationInput): CreateDeckFoundationResult {
+  const outputPath = normalizeOutputPath(input.outputPath)
+  const targetPath = safeWorkspaceFilePath(input.workspaceRoot, outputPath)
+  const mode = input.mode ?? "create"
+  const canOverwrite = input.overwrite === true || mode === "repair"
+  const existed = existsSync(targetPath)
+
+  if (existed && !canOverwrite) {
+    throw new Error(`Deck HTML already exists at ${outputPath}. Pass overwrite=true or mode=repair to replace the foundation shell.`)
+  }
+
+  const design = input.designName || activeDesign()
+  const foundation = getDesignSection("foundation", design)
+  const parts = parseFoundationParts(foundation)
+  if (parts.cssBlocks.length === 0) throw new Error(`Design '${design}' foundation does not include a CSS code block.`)
+  if (parts.scriptBlocks.length === 0) throw new Error(`Design '${design}' foundation does not include a SlidePresentation JavaScript code block.`)
+
+  const html = renderFoundationHtml({
+    language: input.language || "en",
+    title: input.title || "Revela Deck",
+    fontLinks: parts.fontLinks,
+    css: parts.cssBlocks.join("\n\n"),
+    script: parts.scriptBlocks.map(guardEmptyDeckNavigation).join("\n\n"),
+  })
+
+  mkdirSync(dirname(targetPath), { recursive: true })
+  writeFileSync(targetPath, html, "utf-8")
+
+  return {
+    ok: true,
+    outputPath,
+    design,
+    includedSections: [
+      "design:foundation",
+      parts.fontLinks.length > 0 ? "foundation:font-links" : "foundation:font-links:none",
+      "foundation:css",
+      "foundation:SlidePresentation",
+    ],
+    status: existed ? "updated" : "created",
+    next: [
+      "Fetch active design rules before patching slides.",
+      "Fetch required layouts and components from the design before adding slide content.",
+      "Patch slides between the revela-slides markers chapter by chapter, then run artifact QA.",
+    ],
+  }
+}
+
+export function normalizeOutputPath(outputPath: string): string {
+  const trimmed = outputPath.trim()
+  if (!trimmed) throw new Error("outputPath is required")
+  if (!trimmed.endsWith(".html")) throw new Error("Deck foundation outputPath must end in .html")
+  if (isAbsolute(trimmed)) throw new Error("Deck foundation outputPath must be workspace-relative")
+  const segments = trimmed.split(/[\\/]+/)
+  if (segments.includes("..")) throw new Error("Deck foundation outputPath must not contain parent-directory traversal")
+  return normalize(trimmed).replace(/\\/g, "/")
+}
+
+function safeWorkspaceFilePath(workspaceRoot: string, outputPath: string): string {
+  const root = resolve(workspaceRoot)
+  const target = resolve(root, outputPath)
+  if (target !== root && !target.startsWith(`${root}/`)) {
+    throw new Error("Deck foundation outputPath must stay inside the workspace")
+  }
+  return target
+}
+
+function parseFoundationParts(foundation: string): FoundationParts {
+  const fontLinks = extractFontLinks(foundation)
+  const cssBlocks: string[] = []
+  const scriptBlocks: string[] = []
+  const fenceRe = /```([\w-]*)\n([\s\S]*?)```/g
+  let match: RegExpExecArray | null
+
+  while ((match = fenceRe.exec(foundation)) !== null) {
+    const lang = (match[1] || "").toLowerCase()
+    const body = match[2].trim()
+    if (!body) continue
+    if (lang === "css") cssBlocks.push(body)
+    if ((lang === "javascript" || lang === "js") && body.includes("class SlidePresentation")) {
+      scriptBlocks.push(body)
+    }
+  }
+
+  return { fontLinks, cssBlocks, scriptBlocks }
+}
+
+function extractFontLinks(foundation: string): string[] {
+  const links: string[] = []
+  const seen = new Set<string>()
+  const linkRe = /<link\b[^>]*(?:fonts\.googleapis|fonts\.gstatic|rel=["']preconnect["'])[^>]*>/gi
+  let match: RegExpExecArray | null
+  while ((match = linkRe.exec(foundation)) !== null) {
+    const link = match[0].trim()
+    if (seen.has(link)) continue
+    seen.add(link)
+    links.push(link)
+  }
+  return links
+}
+
+function guardEmptyDeckNavigation(script: string): string {
+  return script.replace(
+    /new\s+SlidePresentation\s*\(\s*\)\s*;?/g,
+    'if (document.querySelector(".slide")) { new SlidePresentation(); }',
+  )
+}
+
+function renderFoundationHtml(input: {
+  language: string
+  title: string
+  fontLinks: string[]
+  css: string
+  script: string
+}): string {
+  const fontLinks = input.fontLinks.map((link) => `    ${link}`).join("\n")
+  return [
+    "<!DOCTYPE html>",
+    `<html lang="${escapeAttribute(input.language)}">`,
+    "<head>",
+    "    <meta charset=\"UTF-8\">",
+    "    <meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\">",
+    `    <title>${escapeHtml(input.title)}</title>`,
+    fontLinks,
+    "    <style>",
+    input.css,
+    "    </style>",
+    "</head>",
+    "<body>",
+    `    ${SLIDES_START}`,
+    `    ${SLIDES_END}`,
+    "    <script>",
+    input.script,
+    "    </script>",
+    "</body>",
+    "</html>",
+    "",
+  ].filter((line) => line !== "").join("\n")
+}
+
+function escapeHtml(value: string): string {
+  return value
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#39;")
+}
+
+function escapeAttribute(value: string): string {
+  return escapeHtml(value.trim() || "en")
+}
+
+export function deckFoundationMarkers(): { start: string; end: string } {
+  return { start: SLIDES_START, end: SLIDES_END }
+}

package/lib/qa/index.ts

@@ -79,6 +79,7 @@ function scanAssetRefs(htmlFilePath: string): LayoutIssue[] {
     const ref = raw.trim()
     if (!ref || ref.startsWith("data:") || ref.startsWith("#") || ref.startsWith("mailto:") || ref.startsWith("tel:")) continue
     if (/^https?:\/\//i.test(ref) || ref.startsWith("//")) {
+      if (isAllowedRemoteRuntimeRef(ref)) continue
       issues.push({ type: "asset", sub: "remote_url", severity: "error", detail: `Deck HTML references remote asset URL \`${ref}\`. Save network images to workspace assets and reference the local file instead.` })
       continue
     }
@@ -96,6 +97,17 @@ function scanAssetRefs(htmlFilePath: string): LayoutIssue[] {
   return issues
 }
 
+function isAllowedRemoteRuntimeRef(ref: string): boolean {
+  try {
+    const url = new URL(ref.startsWith("//") ? `https:${ref}` : ref)
+    if (url.hostname === "fonts.googleapis.com" || url.hostname === "fonts.gstatic.com") return true
+    if (url.hostname === "cdn.jsdelivr.net" && url.pathname.startsWith("/npm/echarts@")) return true
+  } catch {
+    return false
+  }
+  return false
+}
+
 function looksLikeImageRef(ref: string): boolean {
   return /\.(?:png|jpe?g|webp|gif|svg)(?:[?#].*)?$/i.test(ref)
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyber-dash-tech/revela",
-  "version": "0.17.5",
+  "version": "0.17.6",
   "description": "OpenCode plugin for trusted narrative artifacts from local sources, research, and evidence",
   "type": "module",
   "main": "./index.ts",

package/plugin.ts

@@ -81,6 +81,7 @@ import decksTool from "./tools/decks"
 import designsAuthorTool from "./tools/designs-author"
 import designsTool from "./tools/designs"
 import domainsTool from "./tools/domains"
+import deckFoundationTool from "./tools/deck-foundation"
 import mediaBatchSaveTool from "./tools/media-batch-save"
 import mediaSaveTool from "./tools/media-save"
 import researchImagesListTool from "./tools/research-images-list"
@@ -586,6 +587,7 @@ const server: Plugin = (async (pluginCtx) => {
     tool: {
       "revela-decks": decksTool,
       "revela-designs": designsTool,
+      "revela-deck-foundation": deckFoundationTool,
       "revela-designs-author": designsAuthorTool,
       "revela-domains": domainsTool,
       "revela-media-batch-save": mediaBatchSaveTool,

package/skill/SKILL.md

@@ -64,8 +64,13 @@ handoff exactly:
 5. Use `readDeckPlan` to inspect the current `deck-plan/` projection before
    artifact review or HTML generation. Diagnostics are advisory unless they are
    artifact validity errors handled by QA.
-6. Fetch the required design layouts/components with `revela-designs read`.
-7. Write HTML when the user proceeds and the deck contract can be satisfied.
+6. For a new deck HTML file, call `revela-deck-foundation` to create the
+   active-design foundation shell. The helper is file-native and must not create
+   narrative slide content, choose layouts/components, or read/write `DECKS.json`.
+7. Fetch the required design rules, layouts, and components with
+   `revela-designs read`.
+8. Patch slides between the foundation shell's `revela-slides` markers when the
+   user proceeds and the deck contract can be satisfied.
 
 Before any HTML generation, call `revela-decks` action `readDeckPlan` and follow
 the current `deck-plan/`: Source Authority, deck parameters, Chapter Writing
@@ -164,7 +169,8 @@ one broad `write`, `edit`, or `apply_patch` call.
 
 For decks with 5 or more slides:
 
-- First create a stable HTML shell plus structural slides and the first chapter.
+- First call `revela-deck-foundation` for new files, then patch structural
+  slides and the first chapter between the `revela-slides` markers.
 - Then fill or revise exactly one chapter range at a time.
 - Do not mix multiple central-claim chapters in the same write.
 - Chapter divider or chapter TOC slides are allowed as structural wayfinding and
@@ -193,14 +199,17 @@ If a write produces QA hard errors, fix them before continuing.
 Before writing or materially changing HTML:
 
 1. Read the deck-plan projection's layout and component names.
-2. Call `revela-designs` with `action: "read"` and `section: "rules"` to fetch
+2. For a new deck HTML file, call `revela-deck-foundation` before adding slide
+   content. Use `mode: "repair"` only for explicit foundation repair or QA
+   foundation contract fixes, not normal Review Comment edits.
+3. Call `revela-designs` with `action: "read"` and `section: "rules"` to fetch
    the active design's current composition and usage rules.
-3. Call `revela-designs` with `action: "read"` and `layout` set to all required
+4. Call `revela-designs` with `action: "read"` and `layout` set to all required
    layout names, comma-separated.
-4. Call `revela-designs` with `action: "read"` and `component` set to all
+5. Call `revela-designs` with `action: "read"` and `component` set to all
    required component names, comma-separated.
-5. Fetch `section: "chart-rules"` before using ECharts.
-6. Do not update legacy `requiredInputs`; design fetching is an execution step,
+6. Fetch `section: "chart-rules"` before using ECharts.
+7. Do not update legacy `requiredInputs`; design fetching is an execution step,
    not a workflow permission gate.
 
 Never generate HTML from memory or prior knowledge of a design. Copy the fetched

package/tools/deck-foundation.ts

@@ -0,0 +1,48 @@
+import { tool } from "@opencode-ai/plugin"
+import { createDeckFoundation } from "../lib/deck-html/foundation"
+
+export default tool({
+  description:
+    "Create or repair a file-native Revela deck HTML foundation shell from the active design. " +
+    "Writes a deterministic empty deck shell with doctype, html/head/body, active design foundation CSS, complete SlidePresentation JavaScript, and stable slide insertion markers. " +
+    "It does not create narrative slide content, choose layouts/components, or read/write DECKS.json.",
+  args: {
+    outputPath: tool.schema
+      .string()
+      .describe("Workspace-relative HTML output path, usually decks/{name}.html."),
+    title: tool.schema
+      .string()
+      .describe("Presentation title for the HTML <title> tag only; this does not create a cover slide."),
+    language: tool.schema
+      .string()
+      .describe("HTML language tag, e.g. en or zh-CN."),
+    designName: tool.schema
+      .string()
+      .optional()
+      .describe("Optional design name. Defaults to the active design."),
+    mode: tool.schema
+      .enum(["create", "repair"])
+      .optional()
+      .describe("create protects existing files unless overwrite=true; repair may replace an existing foundation shell."),
+    overwrite: tool.schema
+      .boolean()
+      .optional()
+      .describe("Whether create mode may overwrite an existing HTML file. Defaults to false."),
+  },
+  async execute(args, { directory }) {
+    try {
+      const result = createDeckFoundation({
+        workspaceRoot: directory || process.cwd(),
+        outputPath: args.outputPath,
+        title: args.title,
+        language: args.language,
+        designName: args.designName,
+        mode: args.mode,
+        overwrite: args.overwrite ?? false,
+      })
+      return JSON.stringify(result, null, 2)
+    } catch (e: any) {
+      return JSON.stringify({ error: e?.message || String(e) })
+    }
+  },
+})