@cyber-dash-tech/revela 0.19.7 → 0.19.9

package/lib/runtime/open-deck.ts

@@ -0,0 +1,190 @@
+import { existsSync, statSync } from "fs"
+import { extname, resolve, sep } from "path"
+import { openUrl as systemOpenUrl } from "../edit/open"
+import { workspaceRelative } from "../workspace-state/rendered-artifacts"
+
+export interface OpenDeckInput {
+  workspaceRoot?: string
+  file: string
+  openBrowser?: boolean
+  openUrl?: (url: string) => void
+}
+
+interface DirectDeckServer {
+  server: ReturnType<typeof Bun.serve>
+  baseUrl: string
+  workspaceRoot: string
+  idleTimer?: Timer
+}
+
+const servers = new Map<string, DirectDeckServer>()
+const IDLE_STOP_MS = 30 * 60 * 1000
+const FALLBACK_PORT_START = 8765
+const FALLBACK_PORT_END = 8899
+
+export function openDeck(input: OpenDeckInput): any {
+  const workspaceRoot = resolve(input.workspaceRoot || process.cwd())
+  const requestedFile = input.file?.trim()
+  if (!requestedFile) {
+    return {
+      ok: false,
+      file: "",
+      error: "Missing required file.",
+      diagnostics: [{ severity: "error", code: "missing_file", message: "Provide a workspace-relative or absolute deck HTML file." }],
+    }
+  }
+
+  const absoluteFile = resolve(workspaceRoot, requestedFile)
+  const file = workspaceRelative(workspaceRoot, absoluteFile)
+  if (!isInside(workspaceRoot, absoluteFile)) {
+    return {
+      ok: false,
+      file,
+      error: `Deck HTML file is outside the workspace: ${file}`,
+      diagnostics: [{ severity: "error", code: "file_outside_workspace", message: `Deck HTML file is outside the workspace: ${file}` }],
+    }
+  }
+  if (!existsSync(absoluteFile) || !statSync(absoluteFile).isFile()) {
+    return {
+      ok: false,
+      file,
+      error: `Deck HTML file not found: ${file}`,
+      diagnostics: [{ severity: "error", code: "file_not_found", message: `Deck HTML file not found: ${file}` }],
+    }
+  }
+  if (!file.startsWith("decks/") || !file.endsWith(".html")) {
+    return {
+      ok: false,
+      file,
+      error: `Deck HTML file must be under decks/*.html: ${file}`,
+      diagnostics: [{ severity: "error", code: "invalid_deck_path", message: `Deck HTML file must be under decks/*.html: ${file}` }],
+    }
+  }
+
+  try {
+    const deckServer = startDeckStaticServer(workspaceRoot)
+    const url = `${deckServer.baseUrl}/${file.split("/").map(encodeURIComponent).join("/")}`
+    const openedBrowser = input.openBrowser !== false
+    if (openedBrowser) (input.openUrl ?? systemOpenUrl)(url)
+    return {
+      ok: true,
+      file,
+      url,
+      serveRoot: workspaceRoot,
+      openedBrowser,
+      mode: "direct",
+      readOnly: true,
+    }
+  } catch (e) {
+    const message = e instanceof Error ? e.message : String(e)
+    return {
+      ok: false,
+      file,
+      error: message,
+      diagnostics: [{ severity: "error", code: "open_deck_failed", message }],
+    }
+  }
+}
+
+export function stopOpenDeckServers(): void {
+  for (const item of servers.values()) {
+    if (item.idleTimer) clearTimeout(item.idleTimer)
+    item.server.stop()
+  }
+  servers.clear()
+}
+
+function startDeckStaticServer(workspaceRoot: string): DirectDeckServer {
+  const existing = servers.get(workspaceRoot)
+  if (existing) {
+    scheduleIdleStop(existing)
+    return existing
+  }
+
+  const server = serveWithFallback(workspaceRoot)
+  const item: DirectDeckServer = {
+    server,
+    baseUrl: `http://127.0.0.1:${server.port}`,
+    workspaceRoot,
+  }
+  ;(server as any).unref?.()
+  servers.set(workspaceRoot, item)
+  scheduleIdleStop(item)
+  return item
+}
+
+function serveWithFallback(workspaceRoot: string): ReturnType<typeof Bun.serve> {
+  const ports = [0, ...Array.from({ length: FALLBACK_PORT_END - FALLBACK_PORT_START + 1 }, (_, index) => FALLBACK_PORT_START + index)]
+  const failures: string[] = []
+  for (const port of ports) {
+    try {
+      return Bun.serve({
+        hostname: "127.0.0.1",
+        port,
+        fetch: (req) => handleStaticRequest(workspaceRoot, req),
+      })
+    } catch (e) {
+      failures.push(`port ${port}: ${e instanceof Error ? e.message : String(e)}`)
+    }
+  }
+  throw new Error(`Failed to start direct deck server. ${failures.slice(0, 3).join(" ")}`)
+}
+
+async function handleStaticRequest(workspaceRoot: string, req: Request): Promise<Response> {
+  const url = new URL(req.url)
+  if (req.method !== "GET" && req.method !== "HEAD") return new Response("Method not allowed", { status: 405 })
+  if (url.pathname === "/health") return new Response("ok", { status: 200 })
+  const pathPart = decodeURIComponent(url.pathname.replace(/^\/+/, ""))
+  if (!pathPart) return new Response("Not found", { status: 404 })
+  const absolutePath = resolve(workspaceRoot, pathPart)
+  if (!isInside(workspaceRoot, absolutePath)) return new Response("Forbidden", { status: 403 })
+  if (!existsSync(absolutePath) || !statSync(absolutePath).isFile()) return new Response("Not found", { status: 404 })
+  const file = Bun.file(absolutePath)
+  const headers = new Headers({ "content-type": contentType(absolutePath) })
+  if (req.method === "HEAD") return new Response(null, { status: 200, headers })
+  return new Response(file, { headers })
+}
+
+function scheduleIdleStop(item: DirectDeckServer): void {
+  if (item.idleTimer) clearTimeout(item.idleTimer)
+  item.idleTimer = setTimeout(() => {
+    item.server.stop()
+    servers.delete(item.workspaceRoot)
+  }, IDLE_STOP_MS)
+}
+
+function isInside(root: string, candidate: string): boolean {
+  const normalizedRoot = resolve(root)
+  const normalizedCandidate = resolve(candidate)
+  return normalizedCandidate === normalizedRoot || normalizedCandidate.startsWith(normalizedRoot.endsWith(sep) ? normalizedRoot : normalizedRoot + sep)
+}
+
+function contentType(filePath: string): string {
+  switch (extname(filePath).toLowerCase()) {
+    case ".html":
+      return "text/html; charset=utf-8"
+    case ".css":
+      return "text/css; charset=utf-8"
+    case ".js":
+      return "application/javascript; charset=utf-8"
+    case ".json":
+      return "application/json; charset=utf-8"
+    case ".svg":
+      return "image/svg+xml"
+    case ".png":
+      return "image/png"
+    case ".jpg":
+    case ".jpeg":
+      return "image/jpeg"
+    case ".webp":
+      return "image/webp"
+    case ".gif":
+      return "image/gif"
+    case ".woff":
+      return "font/woff"
+    case ".woff2":
+      return "font/woff2"
+    default:
+      return "application/octet-stream"
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyber-dash-tech/revela",
-  "version": "0.19.7",
+  "version": "0.19.9",
   "description": "Codex-first CLI/MCP workspace for trusted narrative artifacts from local sources, research, and evidence",
   "type": "module",
   "main": "./index.ts",

package/plugins/revela/.codex-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "revela",
-  "version": "0.19.7",
-  "description": "Use Revela in Codex to specify, research, plan, make, and export trusted narrative decision artifacts.",
+  "version": "0.19.9",
+    "description": "Use Revela in Codex to specify, research, plan, make, review, and export trusted narrative decision artifacts.",
   "author": {
     "name": "cyber-dash-tech",
     "url": "https://github.com/cyber-dash-tech"
@@ -20,7 +20,7 @@
   "interface": {
     "displayName": "Revela",
     "shortDescription": "Trusted narrative artifacts from local sources and research.",
-    "longDescription": "Revela helps Codex route workspace workflows, capture requirements in spec.md, ingest local materials, save research findings, plan decks, generate HTML deck artifacts, open them in Codex Browser for annotation, and export PDF/PPTX/PNG outputs while preserving source traceability.",
+    "longDescription": "Revela helps Codex route workspace workflows, capture requirements in spec.md, ingest local materials, save research findings, plan decks, generate HTML deck artifacts, open them directly in Codex Browser, and export PDF/PPTX/PNG outputs while preserving source traceability.",
     "developerName": "cyber-dash-tech",
     "category": "Productivity",
     "capabilities": [
@@ -31,6 +31,7 @@
       "Use Revela to route the next workflow step for this workspace.",
       "Use Revela to write a spec.md for this deck objective.",
       "Use Revela to make a deck from the deck plan.",
+      "Use Revela to review this deck in Codex Browser.",
       "Use Revela to export this deck artifact."
     ],
     "brandColor": "#2563EB"

package/plugins/revela/mcp/revela-server.ts

@@ -30,6 +30,7 @@ type RuntimeModule = {
   designReadLayout(input: any): any
   designReadComponent(input: any): any
   designActivate(input: any): any
+  switchDeckDesign(input: any): any
   designCreate(input: any): any
   designValidate(input: any): any
   designPreview(input: any): any
@@ -47,7 +48,7 @@ type RuntimeModule = {
   domainDraftValidate(input: any): any
   domainDraftInstall(input: any): any
   reviewDeckRead(input: any): Promise<any>
-  reviewDeckOpen(input: any): Promise<any>
+  openDeck(input: any): Promise<any>
   researchSave(input: any): any
   prepareLocalMaterials(input: any): Promise<any>
   extractMaterial(input: any): Promise<any>
@@ -242,6 +243,16 @@ const tools = [
     description: "Activate a Revela design for future deck planning and artifact generation.",
     inputSchema: objectSchema({ name: requiredStringProp("Design name to activate.") }, ["name"]),
   },
+  {
+    name: "revela_switch_deck_design",
+    description: "Switch one existing decks/*.html artifact to a design by refreshing its deck-local active design snapshot without rewriting slide content.",
+    inputSchema: objectSchema({
+      workspaceRoot: stringProp("Optional workspace root."),
+      file: requiredStringProp("Workspace-relative or absolute decks/*.html file."),
+      name: requiredStringProp("Design name to use for this deck."),
+      openBrowser: booleanProp("Whether to open the switched deck in Codex Browser. Defaults to true."),
+    }, ["file", "name"]),
+  },
   {
     name: "revela_design_create",
     description: "Create and validate a local Revela design package from complete DESIGN.md, design.css, and optional legacy preview.html content.",
@@ -380,7 +391,7 @@ const tools = [
   },
   {
     name: "revela_review_deck_read",
-    description: "Compatibility-only read of aggregate Review diagnostics for a Revela HTML deck: artifact QA, deck-plan diagnostics, and export/readiness signals.",
+    description: "Read optional Review diagnostics for a Revela HTML deck: artifact QA, deck-plan diagnostics, and export/readiness signals.",
     inputSchema: objectSchema({
       workspaceRoot: stringProp("Optional workspace root."),
       file: requiredStringProp("Workspace-relative or absolute HTML deck path."),
@@ -388,12 +399,11 @@ const tools = [
     }, ["file"]),
   },
   {
-    name: "revela_review_deck_open",
-    description: "Compatibility-only opener for the legacy local Codex-backed Review UI for a Revela HTML deck.",
+    name: "revela_open_deck",
+    description: "Open a Revela HTML deck directly in Codex Browser through a read-only localhost URL for user review.",
     inputSchema: objectSchema({
       workspaceRoot: stringProp("Optional workspace root."),
       file: requiredStringProp("Workspace-relative or absolute HTML deck path."),
-      bridge: enumProp(["codex-exec"], "Prompt bridge for browser saved-comment Apply interactions."),
       openBrowser: booleanProp("Whether the tool should open the browser itself. Defaults to true when omitted."),
     }, ["file"]),
   },
@@ -524,6 +534,7 @@ async function callTool(name: string, args: any): Promise<any> {
   if (name === "revela_design_read_layout") return r.designReadLayout(args)
   if (name === "revela_design_read_component") return r.designReadComponent(args)
   if (name === "revela_design_activate") return r.designActivate(args)
+  if (name === "revela_switch_deck_design") return r.switchDeckDesign(args)
   if (name === "revela_design_create") return r.designCreate(args)
   if (name === "revela_design_validate") return r.designValidate(args)
   if (name === "revela_design_draft_create") return r.designDraftCreate(args)
@@ -541,7 +552,7 @@ async function callTool(name: string, args: any): Promise<any> {
   if (name === "revela_domain_draft_validate") return r.domainDraftValidate(args)
   if (name === "revela_domain_draft_install") return r.domainDraftInstall(args)
   if (name === "revela_review_deck_read") return r.reviewDeckRead(args)
-  if (name === "revela_review_deck_open") return r.reviewDeckOpen(args)
+  if (name === "revela_open_deck") return r.openDeck(args)
   if (name === "revela_research_save") return r.researchSave(args)
   if (name === "revela_prepare_local_materials") return r.prepareLocalMaterials(args)
   if (name === "revela_extract_document_materials") return r.extractMaterial(args)

package/plugins/revela/skills/revela/SKILL.md

@@ -29,7 +29,7 @@ Use this skill as the main Revela entrypoint in Codex. It should inspect intent
 - `spec.md` exists but source support, material review, or findings are missing: use `revela-research`.
 - `spec.md` and sufficient findings exist but `deck-plan.md` is missing or needs normal authoring: use `revela-research` Planning Handoff.
 - Valid `deck-plan.md` exists and the user asks to make, generate, render, or update a deck: use `revela-make-deck`.
-- Existing deck artifact and the user asks to review, annotate, diagnose, QA, or refine: use Codex Browser's native browsing/annotation flow. If the deck was not just generated, start a read-only local static server from the workspace root, reply with the existing deck as a localhost website card/link, and use native annotations after the user opens it; route export requests to `revela-export`.
+- Existing deck artifact and the user asks to review, annotate, diagnose, QA, inspect, comment, or refine: use `revela-review`.
 - Existing deck artifact and the user asks for PDF, PPTX, or PNG output: use `revela-export`.
 - If the next step is still ambiguous after inspection, ask the smallest missing question and recommend the safest next specialist skill.
 

package/plugins/revela/skills/revela-design/SKILL.md

@@ -27,7 +27,8 @@ For status, inspection, activation, or selection:
 
 1. Call `revela_design_list`.
 2. Call `revela_design_read`, `revela_design_inventory`, `revela_design_read_layout`, `revela_design_read_component`, or `revela_page_template_foundation` as needed.
-3. Call `revela_design_activate` only when the user asks to use a design.
+3. Call `revela_design_activate` only when the user asks to use a design for future planning/rendering.
+4. For an existing `decks/*.html` artifact, call `revela_switch_deck_design` with the deck file and design name. This refreshes the deck-local active design snapshot and can reopen the deck without rewriting slide content.
 
 For new or edited designs:
 
@@ -41,7 +42,7 @@ For new or edited designs:
 8. Call `revela_design_preview` for the draft, start a read-only local static server from the returned `browserHandoff.serveRoot`, and reply with the resulting localhost preview link for the user to open in Codex Browser.
 9. If validation or preview review fails, revise the draft content and repeat draft create/validate/preview.
 10. Call `revela_design_draft_install` only after the draft validates and the user intent is to install it.
-11. Call `revela_design_activate` only when the user asks to make it active.
+11. Call `revela_design_activate` only when the user asks to make it active for future work; use `revela_switch_deck_design` for an already-rendered deck.
 
 For sharing or installing design archives:
 
@@ -78,13 +79,13 @@ Use `revela_design_create` only when the user explicitly requests direct local c
 - Asset metadata surfaced by read/inventory tools when `assets/**` exists.
 - Saved asset paths and intended uses, for example `assets/cover-background.png -> cover hero background`.
 - Validation result and any remaining diagnostics.
-- Whether the design was activated.
+- Whether the design was activated or an existing deck was switched to that design.
 - Next step, usually `revela-research` for planning with the design or `revela-make-deck` when a valid `deck-plan.md` already exists.
 
 ## Must Not
 
 - Do not write `deck-plan.md`.
-- Do not write `decks/*.html`.
+- Do not rewrite slide content in `decks/*.html` while switching design; use `revela_switch_deck_design` to refresh the deck-local active CSS/assets snapshot.
 - Do not patch `decks/_revela-design/**/design.css`; those files are regenerated deck-local snapshots.
 - Do not install or activate a design unless the user requested that outcome.
 - Do not invent licenses, asset provenance, or brand permissions.

package/plugins/revela/skills/revela-helper/SKILL.md

@@ -46,7 +46,7 @@ Report:
   - `spec.md` exists but no `researches/`: run `revela-research`.
   - Research exists but no `deck-plan.md`: continue `revela-research` to the Planning Handoff.
   - Valid `deck-plan.md` but no deck artifact: run `revela-make-deck`.
-  - Existing deck artifact: start a read-only local static server from the workspace root and surface the HTML deck as a localhost website card/link for Codex Browser native annotation, or run `revela-export` for PDF/PPTX/PNG.
+  - Existing deck artifact: run `revela-review` to open the HTML deck directly in Codex Browser, or run `revela-export` for PDF/PPTX/PNG.
 
 ## Must Not
 

package/plugins/revela/skills/revela-review/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: revela-review
+description: Open an existing Revela HTML deck directly in Codex Browser for user inspection.
+---
+
+# Revela Review
+
+Use this skill when the user asks to review, open, inspect, or look at an existing Revela HTML deck artifact in Codex Browser.
+
+## Contract
+
+- Review is the user-facing browser step after a deck exists.
+- The default path opens the HTML deck itself in Codex Browser without running QA first.
+- Diagnostics are optional: call `revela_review_deck_read` only when the user explicitly asks for QA, readiness, diagnostics, or a written review summary.
+- This skill does not open the legacy comment/apply browser surface, render new decks, or export PDF/PPTX/PNG.
+
+## Preconditions
+
+- Required: a readable `decks/*.html` file or a user-provided deck HTML file path.
+- If the user gives `@decks/<file>.html`, use that file.
+- If the user asks to review "the deck" and exactly one `decks/*.html` file is present, use it.
+- If multiple deck HTML files are present and the target is unclear, ask the user which deck to open.
+
+## Required Tool
+
+Call `revela_open_deck` with:
+
+- `workspaceRoot` when known.
+- `file` set to the workspace-relative or absolute HTML deck path.
+- `openBrowser` omitted or `true` for the normal user-facing flow.
+
+## Optional Diagnostics
+
+When the user explicitly asks for QA, readiness, diagnostics, or a written review summary:
+
+1. Call `revela_review_deck_read` with the target deck file.
+2. Report artifact QA and deck-plan diagnostics concisely.
+3. Still open Review unless the file is missing or the user asked only for diagnostics.
+
+## Output
+
+Report:
+
+- The deck file opened.
+- The direct deck URL returned by `revela_open_deck`.
+- Whether Codex opened the browser.
+- A short user prompt for what to inspect: copy, argument flow, hierarchy, spacing, charts/tables, visuals, and export readiness.
+- If diagnostics were requested, include the concise diagnostic summary.
+
+## Must Not
+
+- Do not run QA before opening Review unless the user explicitly asks for diagnostics.
+- Do not open any legacy comment/apply browser surface or token-based review UI.
+- Do not call export tools; route PDF/PPTX/PNG requests to `revela-export`.
+- Do not generate or rewrite `deck-plan.md`.
+- Do not generate a new HTML deck; route rendering requests to `revela-make-deck`.
+- Do not open local deck files directly with `file://`; use the direct deck opener.