@cyber-dash-tech/revela 0.8.9 → 0.10.0

package/lib/inspect/open.ts

@@ -0,0 +1,61 @@
+import { existsSync } from "fs"
+import { ACTIVE_PROMPT_FILE } from "../config"
+import { ctx } from "../ctx"
+import { seedBuiltinDesigns } from "../design/designs"
+import { seedBuiltinDomains } from "../domain/domains"
+import { ensureEditableDeckState } from "../edit/deck-state"
+import { openUrl } from "../edit/open"
+import { resolveEditableDeck, type EditableDeck } from "../edit/resolve-deck"
+import { buildPrompt } from "../prompt-builder"
+import { startInspectServer } from "./server"
+
+export interface OpenInspectDeckResult {
+  deck: EditableDeck
+  url: string
+  source: string
+  stateNote: string
+  preflightChanged: boolean
+  reusedSession: boolean
+  openedBrowser: boolean
+}
+
+export interface OpenInspectDeckOptions {
+  client: any
+  sessionID: string
+  workspaceRoot: string
+  openBrowser?: boolean
+  openUrl?: (url: string) => void
+}
+
+export function openInspectDeck(target: string, options: OpenInspectDeckOptions): OpenInspectDeckResult {
+  const deck = resolveEditableDeck(options.workspaceRoot, target)
+  const preflight = ensureEditableDeckState(options.workspaceRoot, deck)
+
+  ctx.enabled = true
+  if (!existsSync(ACTIVE_PROMPT_FILE)) {
+    seedBuiltinDesigns()
+    seedBuiltinDomains()
+    buildPrompt()
+  }
+
+  const inspectServer = startInspectServer()
+  const session = inspectServer.getOrCreateSession({
+    client: options.client,
+    sessionID: options.sessionID,
+    workspaceRoot: options.workspaceRoot,
+    deck,
+  })
+  const url = `${inspectServer.baseUrl}/inspect?token=${encodeURIComponent(session.token)}`
+  const shouldOpen = options.openBrowser !== false
+  if (shouldOpen) (options.openUrl ?? openUrl)(url)
+
+  return {
+    deck,
+    url,
+    source: deck.source === "decks-state" ? "DECKS.json" : deck.source === "file-path" ? "file path" : "fallback path",
+    stateNote: preflight.changed ? "Deck state was prepared in DECKS.json for inspection." : "Deck state already points to this inspection target.",
+    preflightChanged: preflight.changed,
+    reusedSession: session.reused,
+    openedBrowser: shouldOpen,
+  }
+}

package/lib/inspect/prompt.ts

@@ -0,0 +1,32 @@
+import type { InspectionPromptProjection } from "../inspection-context/project"
+
+export function buildInspectionPrompt(input: {
+  requestId: string
+  file: string
+  projection: InspectionPromptProjection
+}): string {
+  return `A user selected slide content in Revela Evidence Inspector. The selection may contain one referenced element, a whole slide, or multiple referenced elements selected with Cmd/Ctrl-click.
+
+Target file: ${input.file}
+Inspection request id: ${input.requestId}
+
+Use the structured projection below to produce the final inspector cards. This is LLM judgment with grounded boundaries: answer the selected object's purpose and source credibility only. Do not edit files. Do not mutate DECKS.json. Do not invent sources, quotes, URLs, page references, caveats, or evidence not present in the projection.
+
+Return the result only by calling the \`revela-inspection-result\` tool with this request id. Do not answer in chat.
+
+Required card model:
+- Purpose: explain why this selected content appears here, what job it serves in the slide purpose, narrative role, deck goal, audience, or narrative brief, and why it matters.
+- Source: if the selection contains a factual claim, number, comparison, conclusion, or recommendation, judge source credibility. Use not_needed for structural, transitional, or purely explanatory content that does not need evidence. Include source trace, warnings, gaps, and caveats here.
+
+Boundaries:
+- Do not hunt for problems. If it works, say it works.
+- Do not recommend edits or fixes; this inspector view only explains purpose and source credibility.
+- Do not turn every caveat into a problem.
+- If confidence is low, use unclear or unknown instead of pretending certainty.
+
+Projection JSON:
+
+\`\`\`json
+${JSON.stringify(input.projection, null, 2)}
+\`\`\``
+}

package/lib/inspect/request.ts

@@ -0,0 +1,70 @@
+import { hasDecksState, readDecksState, type DecksState } from "../decks-state"
+import { compileInspectionContext } from "../inspection-context/compile"
+import { matchInspectionElement, type InspectionElementSnapshot } from "../inspection-context/match"
+import { projectInspectionMatch, type InspectionPromptProjection } from "../inspection-context/project"
+import { buildDeterministicInspectionResult, type InspectionResult } from "../inspection-context/result"
+
+export interface InspectElementResult {
+  requestId?: string
+  result: InspectionResult
+}
+
+export interface InspectElementProjectionResult {
+  requestId?: string
+  projection: InspectionPromptProjection
+  preprocess: InspectionResult
+}
+
+export function inspectElementInState(
+  state: DecksState,
+  snapshot: InspectionElementSnapshot,
+  options: { requestId?: string; staleReason?: string; slug?: string } = {},
+): InspectElementResult {
+  const context = compileInspectionContext(state, options.slug)
+  const match = matchInspectionElement(context, snapshot)
+  const projection = projectInspectionMatch(context, match, snapshot)
+  return {
+    requestId: options.requestId,
+    result: buildDeterministicInspectionResult(projection, {
+      requestId: options.requestId,
+      staleReason: options.staleReason,
+    }),
+  }
+}
+
+export function projectElementInState(
+  state: DecksState,
+  snapshot: InspectionElementSnapshot,
+  options: { requestId?: string; slug?: string } = {},
+): InspectElementProjectionResult {
+  const context = compileInspectionContext(state, options.slug)
+  const match = matchInspectionElement(context, snapshot)
+  const projection = projectInspectionMatch(context, match, snapshot)
+  return {
+    requestId: options.requestId,
+    projection,
+    preprocess: buildDeterministicInspectionResult(projection, { requestId: options.requestId }),
+  }
+}
+
+export function inspectWorkspaceElement(
+  workspaceRoot: string,
+  snapshot: InspectionElementSnapshot,
+  options: { requestId?: string; staleReason?: string; slug?: string } = {},
+): InspectElementResult {
+  if (!hasDecksState(workspaceRoot)) {
+    throw new Error("DECKS.json is required before inspection. Run /revela init first.")
+  }
+  return inspectElementInState(readDecksState(workspaceRoot), snapshot, options)
+}
+
+export function projectWorkspaceElement(
+  workspaceRoot: string,
+  snapshot: InspectionElementSnapshot,
+  options: { requestId?: string; slug?: string } = {},
+): InspectElementProjectionResult {
+  if (!hasDecksState(workspaceRoot)) {
+    throw new Error("DECKS.json is required before inspection. Run /revela init first.")
+  }
+  return projectElementInState(readDecksState(workspaceRoot), snapshot, options)
+}

package/lib/inspect/requests.ts

@@ -0,0 +1,86 @@
+import type { InspectionPromptProjection } from "../inspection-context/project"
+import type { InspectionResult } from "../inspection-context/result"
+
+export type InspectRequestStatus = "pending" | "completed" | "failed" | "expired"
+
+export interface PendingInspectRequest {
+  requestId: string
+  status: InspectRequestStatus
+  projection: InspectionPromptProjection
+  deckVersion: string
+  createdAt: number
+  updatedAt: number
+  result?: InspectionResult
+  error?: string
+}
+
+const REQUEST_TTL_MS = 90 * 1000
+const requests = new Map<string, PendingInspectRequest>()
+
+export function createInspectRequest(input: {
+  requestId: string
+  projection: InspectionPromptProjection
+  deckVersion: string
+}): PendingInspectRequest {
+  cleanupInspectRequests()
+  const now = Date.now()
+  const request: PendingInspectRequest = {
+    requestId: input.requestId,
+    status: "pending",
+    projection: input.projection,
+    deckVersion: input.deckVersion,
+    createdAt: now,
+    updatedAt: now,
+  }
+  requests.set(input.requestId, request)
+  return request
+}
+
+export function getInspectRequest(requestId: string): PendingInspectRequest | undefined {
+  cleanupInspectRequests()
+  const request = requests.get(requestId)
+  if (!request) return undefined
+  if (request.status === "pending" && Date.now() - request.createdAt > REQUEST_TTL_MS) {
+    request.status = "expired"
+    request.error = "Inspection timed out before the LLM submitted a result."
+    request.updatedAt = Date.now()
+  }
+  return request
+}
+
+export function completeInspectRequest(requestId: string, result: InspectionResult): PendingInspectRequest {
+  const request = getInspectRequest(requestId)
+  if (!request) throw new Error(`Unknown inspection request: ${requestId}`)
+  if (request.status !== "pending") throw new Error(`Inspection request is not pending: ${request.status}`)
+  request.status = "completed"
+  request.result = { ...result, requestId }
+  request.updatedAt = Date.now()
+  return request
+}
+
+export function failInspectRequest(requestId: string, error: string): PendingInspectRequest | undefined {
+  const request = getInspectRequest(requestId)
+  if (!request || request.status !== "pending") return request
+  request.status = "failed"
+  request.error = error
+  request.updatedAt = Date.now()
+  return request
+}
+
+export function cleanupInspectRequests(now = Date.now()): void {
+  for (const [requestId, request] of requests) {
+    if (request.status === "pending" && now - request.createdAt > REQUEST_TTL_MS) {
+      request.status = "expired"
+      request.error = "Inspection timed out before the LLM submitted a result."
+      request.updatedAt = now
+      continue
+    }
+    if (request.status !== "pending" && now - request.updatedAt > REQUEST_TTL_MS) {
+      requests.delete(requestId)
+    }
+  }
+}
+
+export function clearInspectRequestsForTests(): void {
+  requests.clear()
+}