@cyber-dash-tech/revela 0.17.9 → 0.17.11

package/README.md

@@ -2,7 +2,7 @@
 
 **English** | [中文](README.zh-CN.md)
 
-[![npm version](https://img.shields.io/npm/v/@cyber-dash-tech/revela)](https://www.npmjs.com/package/@cyber-dash-tech/revela) [![license](https://img.shields.io/npm/l/@cyber-dash-tech/revela)](LICENSE) [![tests](https://img.shields.io/badge/tests-615%20passing-brightgreen)](tests/) [![OpenCode plugin](https://img.shields.io/badge/OpenCode-plugin-blue)](https://opencode.ai) [![Bun](https://img.shields.io/badge/Bun-%E2%89%A51.0-orange)](https://bun.sh)
+[![npm version](https://img.shields.io/npm/v/@cyber-dash-tech/revela)](https://www.npmjs.com/package/@cyber-dash-tech/revela) [![license](https://img.shields.io/npm/l/@cyber-dash-tech/revela)](LICENSE) [![tests](https://img.shields.io/badge/tests-617%20passing-brightgreen)](tests/) [![OpenCode plugin](https://img.shields.io/badge/OpenCode-plugin-blue)](https://opencode.ai) [![Bun](https://img.shields.io/badge/Bun-%E2%89%A51.0-orange)](https://bun.sh)
 
 <p align="center">
   <img src="assets/img/logo.png" alt="Revela" width="560" />
@@ -31,14 +31,30 @@ To install globally, add the same entry to `~/.config/opencode/opencode.json`.
 
 ### Codex
 
+Requirements:
+
+- The Codex CLI must be installed and the `codex` command must be available in your shell.
+- Your environment must be able to run `npx`; Revela uses `npx -y @cyber-dash-tech/revela@0.17.11 mcp` to start the MCP server.
+- For interactive Review actions, `codex exec` must also work because the Review UI uses it for Insight and Comment/Apply Fix requests.
+
+Optional preflight:
+
+```bash
+codex --version
+codex exec --help
+npx --version
+```
+
 Install Revela through the Codex Git marketplace:
 
 ```bash
-codex plugin marketplace add https://github.com/cyber-dash-tech/revela --ref v0.17.9
+codex plugin marketplace add https://github.com/cyber-dash-tech/revela --ref v0.17.11
 codex plugin add revela@revela
 ```
 
-Install from the full repository ref. Do not use a sparse checkout limited to `plugins/revela`; the Codex plugin resolves the shared runtime, built-in designs, and domains from the repository snapshot.
+The Git marketplace install provides the Codex plugin shell, skills, hooks, and MCP configuration. When Codex starts the Revela MCP server for the first time, it runs `npx -y @cyber-dash-tech/revela@0.17.11 mcp` so npm can fetch the published package and its dependencies.
+
+You do not need to run `bun install` inside the Codex marketplace clone.
 
 Start a new Codex thread after installing so Codex loads the Revela skills, MCP tools, and hooks.
 

package/README.zh-CN.md

@@ -2,7 +2,7 @@
 
 [English](README.md) | **中文**
 
-[![npm version](https://img.shields.io/npm/v/@cyber-dash-tech/revela)](https://www.npmjs.com/package/@cyber-dash-tech/revela) [![license](https://img.shields.io/npm/l/@cyber-dash-tech/revela)](LICENSE) [![tests](https://img.shields.io/badge/tests-615%20passing-brightgreen)](tests/) [![OpenCode plugin](https://img.shields.io/badge/OpenCode-plugin-blue)](https://opencode.ai) [![Bun](https://img.shields.io/badge/Bun-%E2%89%A51.0-orange)](https://bun.sh)
+[![npm version](https://img.shields.io/npm/v/@cyber-dash-tech/revela)](https://www.npmjs.com/package/@cyber-dash-tech/revela) [![license](https://img.shields.io/npm/l/@cyber-dash-tech/revela)](LICENSE) [![tests](https://img.shields.io/badge/tests-617%20passing-brightgreen)](tests/) [![OpenCode plugin](https://img.shields.io/badge/OpenCode-plugin-blue)](https://opencode.ai) [![Bun](https://img.shields.io/badge/Bun-%E2%89%A51.0-orange)](https://bun.sh)
 
 <p align="center">
   <img src="assets/img/logo.png" alt="Revela" width="560" />
@@ -31,14 +31,30 @@ Revela 可在 [OpenCode](https://opencode.ai) 和 Codex 中使用，把来源材
 
 ### Codex
 
+环境要求：
+
+- 需要已安装 Codex CLI，并且 shell 中可以执行 `codex`。
+- 环境中需要可以执行 `npx`；Revela 会用 `npx -y @cyber-dash-tech/revela@0.17.11 mcp` 启动 MCP server。
+- 如果使用 Review UI 的 Insight、Comment 或 Apply Fix，需要 `codex exec` 可用。
+
+可选的安装前检查：
+
+```bash
+codex --version
+codex exec --help
+npx --version
+```
+
 通过 Codex Git marketplace 安装 Revela：
 
 ```bash
-codex plugin marketplace add https://github.com/cyber-dash-tech/revela --ref v0.17.9
+codex plugin marketplace add https://github.com/cyber-dash-tech/revela --ref v0.17.11
 codex plugin add revela@revela
 ```
 
-请从完整仓库 ref 安装。不要使用仅包含 `plugins/revela` 的 sparse checkout；Codex plugin 会从仓库快照中解析 shared runtime、内置 designs 和 domains。
+Git marketplace 安装的是 Codex plugin 壳、skills、hooks 和 MCP 配置。Codex 第一次启动 Revela MCP server 时，会运行 `npx -y @cyber-dash-tech/revela@0.17.11 mcp`，由 npm 获取已发布 package 及其 dependencies。
+
+不需要在 Codex marketplace clone 里运行 `bun install`。
 
 安装后开启一个新的 Codex thread，让 Codex 加载 Revela 的 skills、MCP tools 和 hooks。
 

package/lib/log.ts

@@ -1,28 +1,39 @@
-import { Logger } from "tslog"
-
 /**
- * Revela structured logger (tslog).
- *
- * Log levels:
- *   0 = silly, 1 = trace, 2 = debug, 3 = info, 4 = warn, 5 = error, 6 = fatal
- *
- * Set REVELA_DEBUG=1 to enable debug-level output (minLevel 2).
- * Default minLevel is 3 (info) in production.
+ * Revela logger facade.
+ * Keep this module dependency-free so lightweight runtime tools can load from
+ * Codex Git marketplace checkouts that do not have package dependencies
+ * installed. Logging is intentionally silent by default because Revela often
+ * runs over stdio protocols where stderr noise is user-visible.
  */
-const minLevel = process.env.REVELA_DEBUG === "1" ? 2 : 3
+type LogMethod = (message?: unknown, ...args: unknown[]) => void
+
+export interface RevelaLogger {
+  silly: LogMethod
+  trace: LogMethod
+  debug: LogMethod
+  info: LogMethod
+  warn: LogMethod
+  error: LogMethod
+  fatal: LogMethod
+  getSubLogger(input?: { name?: string }): RevelaLogger
+}
+
+const noop: LogMethod = () => {}
+
+function createNoopLogger(_name = "revela"): RevelaLogger {
+  return {
+    silly: noop,
+    trace: noop,
+    debug: noop,
+    info: noop,
+    warn: noop,
+    error: noop,
+    fatal: noop,
+    getSubLogger: (input?: { name?: string }) => createNoopLogger(input?.name),
+  }
+}
 
-export const log = new Logger({
-  name: "revela",
-  minLevel,
-  type: "json",
-  hideLogPositionForProduction: true,
-  overwrite: {
-    transportJSON: (_logObj: unknown) => {
-      // Silenced: revela runs as an OpenCode plugin; writing to stderr
-      // pollutes the host terminal. Logs are intentionally suppressed.
-    },
-  },
-})
+export const log: RevelaLogger = createNoopLogger()
 
 /**
  * Create a child logger for a specific sub-module.

package/lib/refine/prompt-bridge.ts

@@ -29,9 +29,11 @@ export interface CodexExecRunResult {
 }
 
 export type CodexExecRunner = (input: {
+  action: ReviewPromptAction
   prompt: string
   workspaceRoot: string
   timeoutMs: number
+  sandboxMode: "read-only" | "workspace-write"
 }) => Promise<CodexExecRunResult>
 
 export function createOpenCodeReviewPromptBridge(client: any, sessionID: string): ReviewPromptBridge {
@@ -65,10 +67,13 @@ export function createCodexExecReviewPromptBridge(options: {
   return {
     kind: "codex-exec",
     async send(input) {
+      const sandboxMode = input.action === "comment" ? "workspace-write" : "read-only"
       const output = await runner({
+        action: input.action,
         prompt: input.prompt,
         workspaceRoot: input.workspaceRoot,
         timeoutMs: input.timeoutMs ?? timeoutMs,
+        sandboxMode,
       })
       const raw = [output.stdout, output.stderr].filter(Boolean).join("\n")
       if (output.exitCode !== 0) {
@@ -79,6 +84,14 @@ export function createCodexExecReviewPromptBridge(options: {
           raw,
         }
       }
+      if (input.action === "comment" && isCodexWriteBlocked(raw)) {
+        return {
+          ok: false,
+          status: "failed",
+          error: "codex exec could not write the deck because its sandbox blocked file changes.",
+          raw,
+        }
+      }
       if (input.action === "comment") return { ok: true, status: "completed", raw }
       const result = extractInspectionResult(output.stdout)
       if (!result) {
@@ -95,12 +108,14 @@ export function createCodexExecReviewPromptBridge(options: {
 }
 
 async function runCodexExec(input: {
+  action: ReviewPromptAction
   prompt: string
   workspaceRoot: string
   timeoutMs: number
+  sandboxMode: "read-only" | "workspace-write"
 }): Promise<CodexExecRunResult> {
   return new Promise((resolve) => {
-    const child = spawn("codex", ["exec", "--json", "--ephemeral", "-C", input.workspaceRoot, input.prompt], {
+    const child = spawn("codex", ["exec", "--json", "--ephemeral", "--sandbox", input.sandboxMode, "-C", input.workspaceRoot, input.prompt], {
       stdio: ["ignore", "pipe", "pipe"],
     })
     let stdout = ""
@@ -130,6 +145,15 @@ async function runCodexExec(input: {
   })
 }
 
+function isCodexWriteBlocked(raw: string): boolean {
+  const text = raw.toLowerCase()
+  return (
+    (text.includes("patch rejected") && text.includes("read-only sandbox")) ||
+    text.includes("writing is blocked by read-only sandbox") ||
+    text.includes("blocked by read-only sandbox")
+  )
+}
+
 function extractInspectionResult(stdout: string): InspectionResult | undefined {
   const direct = parseJson(stdout)
   const fromDirect = findInspectionResult(direct)

package/lib/runtime/index.ts

@@ -7,14 +7,10 @@ import { computeNarrativeHash } from "../narrative-state/hash"
 import { compileNarrativeVault } from "../narrative-vault/compile"
 import { runNarrativeMarkdownQa, type MarkdownQaOptions } from "../narrative-vault/markdown-qa"
 import { readDeckPlanArtifact } from "../narrative-state/deck-plan-artifact"
-import { exportToPdf } from "../pdf/export"
-import { exportToPptx } from "../pptx/export"
-import { assertExportQAPassed } from "../qa/export-gate"
-import { formatArtifactQAReport, runArtifactQA } from "../qa/artifact"
 import { extractDesignClasses } from "../design/designs"
 import { recordRenderedArtifact, workspaceRelative } from "../workspace-state/rendered-artifacts"
+import type { ReviewDeckOpenInput, ReviewDeckReadInput } from "./review"
 export { bindResearchFindings, evaluateResearchFindings, researchSave, researchTargets } from "./research"
-export { reviewDeckOpen, reviewDeckRead } from "./review"
 export { storyRead } from "./story"
 
 export interface RuntimeWorkspaceInput {
@@ -91,6 +87,7 @@ export function createDeckFoundation(input: RuntimeDeckFoundationInput) {
 }
 
 export async function runDeckQa(input: RuntimeFileInput) {
+  const { formatArtifactQAReport, runArtifactQA } = await import("../qa/artifact")
   const workspaceRoot = root(input.workspaceRoot)
   const filePath = resolve(workspaceRoot, input.file)
   let vocabulary
@@ -113,6 +110,8 @@ export async function runDeckQa(input: RuntimeFileInput) {
 }
 
 export async function exportPdf(input: RuntimeFileInput) {
+  const { exportToPdf } = await import("../pdf/export")
+  const { assertExportQAPassed } = await import("../qa/export-gate")
   const workspaceRoot = root(input.workspaceRoot)
   const filePath = resolve(workspaceRoot, input.file)
   await assertExportQAPassed(filePath, { workspaceRoot })
@@ -127,6 +126,8 @@ export async function exportPdf(input: RuntimeFileInput) {
 }
 
 export async function exportPptx(input: RuntimeFileInput & { speakerNotes?: Array<string | null | undefined> }) {
+  const { exportToPptx } = await import("../pptx/export")
+  const { assertExportQAPassed } = await import("../qa/export-gate")
   const workspaceRoot = root(input.workspaceRoot)
   const filePath = resolve(workspaceRoot, input.file)
   await assertExportQAPassed(filePath, { workspaceRoot })
@@ -140,6 +141,16 @@ export async function exportPptx(input: RuntimeFileInput & { speakerNotes?: Arra
   return { ok: true, ...result }
 }
 
+export async function reviewDeckRead(input: ReviewDeckReadInput) {
+  const review = await import("./review")
+  return review.reviewDeckRead(input)
+}
+
+export async function reviewDeckOpen(input: ReviewDeckOpenInput) {
+  const review = await import("./review")
+  return review.reviewDeckOpen(input)
+}
+
 export function designList() {
   seedBuiltinDesigns()
   return {

package/package.json

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

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

@@ -1,6 +1,6 @@
 {
   "name": "revela",
-  "version": "0.1.0+codex.20260524121829",
+  "version": "0.1.0+codex.20260524145000",
   "description": "Use Revela in Codex to build trusted, traceable narrative decision artifacts from local sources and research.",
   "author": {
     "name": "cyber-dash-tech",

package/plugins/revela/.mcp.json

@@ -1,11 +1,8 @@
 {
   "mcpServers": {
     "revela": {
-      "command": "bun",
-      "args": [
-        "--eval",
-        "const fs = await import('fs');\nconst path = await import('path');\nconst { pathToFileURL } = await import('url');\nconst candidates = [];\nconst home = process.env.HOME || '';\nconst marketplaceNames = ['revela', 'revela-local'];\ncandidates.push(path.resolve(process.cwd(), 'bin/revela.ts'));\nconst configPath = path.join(home, '.codex', 'config.toml');\nif (fs.existsSync(configPath)) {\n  const text = fs.readFileSync(configPath, 'utf-8');\n  const sections = text.split(/\\n(?=\\s*\\[)/);\n  for (const marketplaceName of marketplaceNames) {\n    const section = sections.find((item) => item.trimStart().startsWith(`[marketplaces.${marketplaceName}]`));\n    const match = section?.match(/^\\s*source\\s*=\\s*\"([^\"]+)\"/m);\n    if (match && !/^[a-z][a-z0-9+.-]*:\\/\\//i.test(match[1])) candidates.push(path.join(match[1], 'bin/revela.ts'));\n  }\n}\nfor (const marketplaceName of marketplaceNames) {\n  candidates.push(path.join(home, '.codex', '.tmp', 'marketplaces', marketplaceName, 'bin/revela.ts'));\n}\nfor (const marketplaceName of marketplaceNames) {\n  const cacheRoot = path.join(home, '.codex', 'plugins', 'cache', marketplaceName, 'revela');\n  if (fs.existsSync(cacheRoot)) {\n    for (const version of fs.readdirSync(cacheRoot).sort().reverse()) candidates.push(path.join(cacheRoot, version, 'bin/revela.ts'));\n  }\n}\nconst cli = candidates.find((candidate) => fs.existsSync(candidate));\nif (!cli) {\n  console.error(`Could not locate Revela CLI. Checked: ${candidates.join(', ')}`);\n  process.exit(1);\n}\nprocess.env.REVELA_CLI_COMMAND = 'mcp';\nawait import(pathToFileURL(cli).href);"
-      ]
+      "command": "npx",
+      "args": ["-y", "@cyber-dash-tech/revela@0.17.11", "mcp"]
     }
   }
 }