@cyber-dash-tech/revela 0.9.0 → 0.10.0

package/lib/inspection-context/project.ts

@@ -0,0 +1,263 @@
+import type { NarrativeBrief, NarrativeRole } from "../decks-state"
+import type { InspectionContext, InspectionEvidenceTrace, InspectionGap } from "./compile"
+import type { InspectionElementMatch, InspectionElementSnapshot, InspectionMatchConfidence } from "./match"
+
+export interface InspectionPromptProjection {
+  version: 1
+  deck: InspectionProjectionDeck
+  selectedElement: InspectionProjectionElement
+  match: InspectionProjectionMatch
+  cards: {
+    source: InspectionSourceProjection
+    evidence: InspectionEvidenceProjection
+    caveats: InspectionCaveatsProjection
+    objective: InspectionObjectiveProjection
+    appendix: InspectionAppendixProjection
+  }
+}
+
+export interface InspectionProjectionDeck {
+  slug: string
+  goal: string
+  audience?: string
+  language?: string
+  narrativeBrief?: NarrativeBrief
+}
+
+export interface InspectionProjectionElement {
+  scope?: "element" | "selection" | "slide"
+  slideIndex?: number
+  text?: string
+  elements?: Array<{
+    text?: string
+    tagName?: string
+    classList: string[]
+    role?: string
+  }>
+  tagName?: string
+  classList: string[]
+  role?: string
+}
+
+export interface InspectionProjectionMatch {
+  confidence: InspectionMatchConfidence
+  reason: string
+  slide?: {
+    index: number
+    title: string
+    purpose?: string
+    narrativeRole?: NarrativeRole
+  }
+  claim?: {
+    id: string
+    origin: string
+    text: string
+    evidenceSensitive: boolean
+    evidenceSupport: string
+  }
+}
+
+export interface InspectionSourceProjection {
+  evidence: InspectionEvidenceProjectionTrace[]
+  missingSourceGaps: InspectionGapProjection[]
+  weakSourceGaps: InspectionGapProjection[]
+}
+
+export interface InspectionEvidenceProjection {
+  matchedClaim?: string
+  evidenceSupport?: string
+  traces: InspectionEvidenceProjectionTrace[]
+  gaps: InspectionGapProjection[]
+}
+
+export interface InspectionCaveatsProjection {
+  caveats: string[]
+}
+
+export interface InspectionObjectiveProjection {
+  slidePurpose?: string
+  narrativeRole?: NarrativeRole
+  deckGoal: string
+  audience?: string
+  decisionOrAction?: string
+  audienceBeliefBefore?: string
+  audienceBeliefAfter?: string
+}
+
+export interface InspectionAppendixProjection {
+  candidates: Array<{
+    slideIndex: number
+    slideTitle: string
+    reason: string
+    evidence: InspectionEvidenceProjectionTrace[]
+  }>
+  relatedRisks: string[]
+  relatedObjections: string[]
+}
+
+export interface InspectionEvidenceProjectionTrace {
+  source: string
+  sourcePath?: string
+  findingsFile?: string
+  location?: string
+  page?: string
+  url?: string
+  quote?: string
+  caveat?: string
+  extractedTextPath?: string
+  extractedManifestPath?: string
+  hasDetail: boolean
+}
+
+export interface InspectionGapProjection {
+  type: string
+  claimText: string
+  message: string
+}
+
+export function projectInspectionMatch(
+  context: InspectionContext,
+  match: InspectionElementMatch,
+  snapshot: InspectionElementSnapshot = {},
+): InspectionPromptProjection {
+  const slide = match.slide
+  const claim = match.claim
+  const traces = match.evidence.map(projectEvidenceTrace)
+  const gaps = match.gaps.map(projectGap)
+  const narrativeBrief = context.narrativeBrief
+
+  return {
+    version: 1,
+    deck: {
+      slug: context.slug,
+      goal: truncate(context.goal, 320),
+      audience: truncateOptional(context.audience, 160),
+      language: truncateOptional(context.language, 80),
+      narrativeBrief: narrativeBrief ? projectNarrativeBrief(narrativeBrief) : undefined,
+    },
+    selectedElement: {
+      slideIndex: snapshot.slideIndex,
+      scope: snapshot.scope,
+      text: truncateOptional(snapshot.selectedText || snapshot.text, 700),
+      elements: snapshot.elements?.slice(0, 12).map((item) => ({
+        text: truncateOptional(item.text, 320),
+        tagName: truncateOptional(item.tagName, 40),
+        classList: (item.classList ?? []).slice(0, 8).map((className) => truncate(className, 80)),
+        role: truncateOptional(item.role, 80),
+      })),
+      tagName: truncateOptional(snapshot.tagName, 40),
+      classList: (snapshot.classList ?? []).slice(0, 12).map((item) => truncate(item, 80)),
+      role: truncateOptional(snapshot.role, 80),
+    },
+    match: {
+      confidence: match.confidence,
+      reason: match.reason,
+      slide: slide
+        ? {
+            index: slide.index,
+            title: truncate(slide.title, 180),
+            purpose: truncateOptional(slide.purpose, 240),
+            narrativeRole: slide.narrativeRole,
+          }
+        : undefined,
+      claim: claim
+        ? {
+            id: claim.id,
+            origin: claim.origin,
+            text: truncate(claim.text, 500),
+            evidenceSensitive: claim.evidenceSensitive,
+            evidenceSupport: claim.evidenceSupport,
+          }
+        : undefined,
+    },
+    cards: {
+      source: {
+        evidence: traces,
+        missingSourceGaps: gaps.filter((gap) => gap.type === "missing_evidence"),
+        weakSourceGaps: gaps.filter((gap) => gap.type === "weak_evidence"),
+      },
+      evidence: {
+        matchedClaim: claim ? truncate(claim.text, 500) : undefined,
+        evidenceSupport: claim?.evidenceSupport,
+        traces,
+        gaps,
+      },
+      caveats: {
+        caveats: match.caveats.map((item) => truncate(item, 280)).slice(0, 8),
+      },
+      objective: {
+        slidePurpose: truncateOptional(slide?.purpose, 240),
+        narrativeRole: slide?.narrativeRole,
+        deckGoal: truncate(context.goal, 320),
+        audience: truncateOptional(context.audience, 160),
+        decisionOrAction: truncateOptional(narrativeBrief?.decisionOrAction, 240),
+        audienceBeliefBefore: truncateOptional(narrativeBrief?.audienceBeliefBefore, 240),
+        audienceBeliefAfter: truncateOptional(narrativeBrief?.audienceBeliefAfter, 240),
+      },
+      appendix: {
+        candidates: match.appendixCandidates.slice(0, 5).map((candidate) => ({
+          slideIndex: candidate.slideIndex,
+          slideTitle: truncate(candidate.slideTitle, 180),
+          reason: truncate(candidate.reason, 240),
+          evidence: candidate.evidence.map(projectEvidenceTrace),
+        })),
+        relatedRisks: relatedNarrativeText(context.riskContext, slide?.index),
+        relatedObjections: relatedNarrativeText(context.objectionContext, slide?.index),
+      },
+    },
+  }
+}
+
+function projectEvidenceTrace(trace: InspectionEvidenceTrace): InspectionEvidenceProjectionTrace {
+  return {
+    source: truncate(trace.source, 180),
+    sourcePath: truncateOptional(trace.sourcePath, 220),
+    findingsFile: truncateOptional(trace.findingsFile, 220),
+    location: truncateOptional(trace.location, 120),
+    page: truncateOptional(trace.page, 80),
+    url: truncateOptional(trace.url, 240),
+    quote: truncateOptional(trace.quote, 500),
+    caveat: truncateOptional(trace.caveat, 280),
+    extractedTextPath: truncateOptional(trace.extractedTextPath, 220),
+    extractedManifestPath: truncateOptional(trace.extractedManifestPath, 220),
+    hasDetail: trace.hasDetail,
+  }
+}
+
+function projectGap(gap: InspectionGap): InspectionGapProjection {
+  return {
+    type: gap.type,
+    claimText: truncate(gap.claimText, 500),
+    message: truncate(gap.message, 280),
+  }
+}
+
+function projectNarrativeBrief(brief: NarrativeBrief): NarrativeBrief {
+  return {
+    audienceBeliefBefore: truncateOptional(brief.audienceBeliefBefore, 240),
+    audienceBeliefAfter: truncateOptional(brief.audienceBeliefAfter, 240),
+    decisionOrAction: truncateOptional(brief.decisionOrAction, 240),
+    narrativeArc: truncateOptional(brief.narrativeArc, 240),
+    keyClaims: brief.keyClaims.map((item) => truncate(item, 240)).slice(0, 8),
+    objections: brief.objections.map((item) => truncate(item, 240)).slice(0, 8),
+    risks: brief.risks.map((item) => truncate(item, 240)).slice(0, 8),
+  }
+}
+
+function relatedNarrativeText(items: InspectionContext["riskContext"], slideIndex: number | undefined): string[] {
+  return items
+    .filter((item) => item.slideIndex === undefined || item.slideIndex === slideIndex)
+    .map((item) => truncate(item.text, 240))
+    .slice(0, 6)
+}
+
+function truncateOptional(value: string | undefined, max: number): string | undefined {
+  if (value === undefined) return undefined
+  return truncate(value, max)
+}
+
+function truncate(value: string, max: number): string {
+  const text = String(value ?? "").replace(/\s+/g, " ").trim()
+  if (text.length <= max) return text
+  return text.slice(0, Math.max(0, max - 3)).trimEnd() + "..."
+}

package/lib/inspection-context/result.ts

@@ -0,0 +1,160 @@
+import type { InspectionMatchConfidence } from "./match"
+import type { InspectionPromptProjection } from "./project"
+
+export type InspectionResultStatus = "success" | "no_match"
+export type InspectionPurposeStatus = "clear" | "weak" | "misplaced" | "unknown"
+export type InspectionSourceStatus = "supported" | "weak" | "unsupported" | "not_needed" | "unknown"
+
+export interface InspectionResult {
+  version: 1
+  requestId?: string
+  status: InspectionResultStatus
+  selectedText?: string
+  slide?: {
+    index: number
+    title: string
+  }
+  matchConfidence: InspectionMatchConfidence
+  cards: {
+    purpose: PurposeCard
+    source: SourceCard
+  }
+  stale?: {
+    stale: boolean
+    reason?: string
+  }
+}
+
+export interface SupportSourceItem {
+  source: string
+  sourcePath?: string
+  findingsFile?: string
+  location?: string
+  page?: string
+  url?: string
+  quote?: string
+  caveat?: string
+}
+
+export interface PurposeCard {
+  status: InspectionPurposeStatus
+  role?: string
+  rationale: string
+  whyItMatters: string
+}
+
+export interface SourceCard {
+  status: InspectionSourceStatus
+  matchedClaim?: string
+  sources: SupportSourceItem[]
+  warnings: string[]
+  gaps: string[]
+  caveats: string[]
+  rationale: string
+}
+
+export function buildDeterministicInspectionResult(
+  projection: InspectionPromptProjection,
+  options: { requestId?: string; staleReason?: string } = {},
+): InspectionResult {
+  const slide = projection.match.slide
+  const evidence = projection.cards.source.evidence
+  const gaps = projection.cards.evidence.gaps
+  const missingGaps = projection.cards.source.missingSourceGaps
+  const weakGaps = projection.cards.source.weakSourceGaps
+  const noMatch = projection.match.confidence === "none" || !slide
+
+  return {
+    version: 1,
+    requestId: options.requestId,
+    status: noMatch ? "no_match" : "success",
+    selectedText: projection.selectedElement.text,
+    slide: slide ? { index: slide.index, title: slide.title } : undefined,
+    matchConfidence: projection.match.confidence,
+    cards: {
+      purpose: {
+        status: purposeStatus(projection, noMatch),
+        role: projection.cards.objective.narrativeRole,
+        rationale: purposeRationale(projection, noMatch),
+        whyItMatters: purposeWhyItMatters(projection, noMatch),
+      },
+      source: {
+        status: sourceStatus(projection, noMatch),
+        matchedClaim: projection.cards.evidence.matchedClaim,
+        sources: evidence.map((item) => ({
+          source: item.source,
+          sourcePath: item.sourcePath,
+          findingsFile: item.findingsFile,
+          location: item.location,
+          page: item.page,
+          url: item.url,
+          quote: item.quote,
+          caveat: item.caveat,
+        })),
+        warnings: sourceWarnings(missingGaps.length, weakGaps.length, noMatch),
+        gaps: gaps.map((gap) => gap.message),
+        caveats: sourceCaveats(projection),
+        rationale: sourceRationale(projection, noMatch),
+      },
+    },
+    stale: options.staleReason ? { stale: true, reason: options.staleReason } : undefined,
+  }
+}
+
+function purposeStatus(projection: InspectionPromptProjection, noMatch: boolean): InspectionPurposeStatus {
+  if (noMatch) return "unknown"
+  if (projection.cards.objective.narrativeRole || projection.cards.objective.slidePurpose) return "clear"
+  return "unknown"
+}
+
+function purposeRationale(projection: InspectionPromptProjection, noMatch: boolean): string {
+  if (noMatch) return "No matched slide is available to explain why this selection appears here."
+  const role = projection.cards.objective.narrativeRole
+  const purpose = projection.cards.objective.slidePurpose
+  if (role && purpose) return `The selection appears inside a ${role} slide whose recorded purpose is: ${purpose}`
+  if (purpose) return `The selection appears on a slide whose recorded purpose is: ${purpose}`
+  if (role) return `The selection appears inside a slide with recorded narrative role: ${role}`
+  return "The deterministic fallback cannot explain placement because the slide has no recorded purpose or narrative role."
+}
+
+function purposeWhyItMatters(projection: InspectionPromptProjection, noMatch: boolean): string {
+  if (noMatch) return "Without a matched slide, the inspector cannot connect this selection to the deck narrative."
+  const deckGoal = projection.cards.objective.deckGoal
+  const audience = projection.cards.objective.audience
+  if (deckGoal && audience) return `It matters because this selection contributes to the deck goal (${deckGoal}) for ${audience}.`
+  if (deckGoal) return `It matters because this selection contributes to the deck goal: ${deckGoal}`
+  if (audience) return `It matters because this selection is part of the message being shaped for ${audience}.`
+  return "It matters as part of this slide's communication job, but the deterministic fallback has limited deck-level intent metadata."
+}
+
+function sourceStatus(projection: InspectionPromptProjection, noMatch: boolean): InspectionSourceStatus {
+  if (noMatch) return "unknown"
+  if (projection.cards.source.missingSourceGaps.length > 0) return "unsupported"
+  if (projection.cards.source.weakSourceGaps.length > 0) return "weak"
+  if (projection.cards.evidence.traces.some((item) => item.hasDetail)) return "supported"
+  return projection.match.claim?.evidenceSensitive ? "unsupported" : "not_needed"
+}
+
+function sourceWarnings(missingGapCount: number, weakGapCount: number, noMatch: boolean): string[] {
+  if (noMatch) return ["No slide or claim matched the selected element."]
+  const warnings: string[] = []
+  if (missingGapCount > 0) warnings.push("Matched evidence-sensitive claim has no slide-level evidence trace.")
+  if (weakGapCount > 0) warnings.push("Matched evidence is source-only and lacks quote, location, URL, caveat, findings file, or source path detail.")
+  return warnings
+}
+
+function sourceRationale(projection: InspectionPromptProjection, noMatch: boolean): string {
+  if (noMatch) return "No matched claim is available for support assessment."
+  if (projection.cards.source.missingSourceGaps.length > 0) return "The selected evidence-sensitive wording is unsupported in the current slide state."
+  if (projection.cards.source.weakSourceGaps.length > 0) return "The selected wording has evidence, but the trace is source-only or missing inspection detail."
+  if (projection.cards.evidence.traces.some((item) => item.hasDetail)) return "The selected wording has detailed slide-level evidence trace, including source detail where available."
+  return "The selection is not clearly evidence-sensitive, so source support is not needed by the deterministic fallback."
+}
+
+function sourceCaveats(projection: InspectionPromptProjection): string[] {
+  return [
+    ...projection.cards.caveats.caveats,
+    ...projection.cards.appendix.relatedRisks,
+    ...projection.cards.appendix.relatedObjections,
+  ].slice(0, 10)
+}

package/lib/refine/open.ts

@@ -0,0 +1,68 @@
+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 { startRefineServer, type RefineMode } from "./server"
+
+export interface OpenRefineDeckResult {
+  deck: EditableDeck
+  url: string
+  source: string
+  stateNote: string
+  preflightChanged: boolean
+  reusedSession: boolean
+  liveSession: boolean
+  openedBrowser: boolean
+  mode: RefineMode
+}
+
+export interface OpenRefineDeckOptions {
+  client: any
+  sessionID: string
+  workspaceRoot: string
+  mode?: RefineMode
+  openBrowser?: boolean
+  openUrl?: (url: string) => void
+}
+
+export function openRefineDeck(target: string, options: OpenRefineDeckOptions): OpenRefineDeckResult {
+  const deck = resolveEditableDeck(options.workspaceRoot, target)
+  const preflight = ensureEditableDeckState(options.workspaceRoot, deck)
+  const mode = options.mode ?? "edit"
+
+  ctx.enabled = true
+  if (!existsSync(ACTIVE_PROMPT_FILE)) {
+    seedBuiltinDesigns()
+    seedBuiltinDomains()
+    buildPrompt()
+  }
+
+  const refineServer = startRefineServer()
+  const session = refineServer.getOrCreateSession({
+    client: options.client,
+    sessionID: options.sessionID,
+    workspaceRoot: options.workspaceRoot,
+    deck,
+    mode,
+  })
+  const url = `${refineServer.baseUrl}/refine?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 refinement." : "Deck state already points to this refinement target.",
+    preflightChanged: preflight.changed,
+    reusedSession: session.reused,
+    liveSession: session.live,
+    openedBrowser: shouldOpen,
+    mode,
+  }
+}