@cyber-dash-tech/revela 0.17.21 → 0.17.23

package/lib/design/designs.ts

@@ -1,11 +1,9 @@
 /**
  * DesignManager — manage revela visual design templates.
  *
- * Designs are stored in ~/.config/revela/designs/<name>/.
+ * User designs are stored in ~/.config/revela/designs/<name>/.
+ * Built-in designs are shipped read-only with this package under designs/<name>/.
  * Each design directory contains DESIGN.md (required) and optionally preview.html.
- *
- * Built-in designs are shipped with the npm package under designs/ and seeded
- * to the config directory on first run.
  */
 
 import {
@@ -152,21 +150,46 @@ export function parseDesignFile(filePath: string): DesignInfo | null {
 // Public API
 // ---------------------------------------------------------------------------
 
-/** List installed designs, sorted by name. Internal designs are hidden by default. */
+function designDirHasPackage(dir: string): boolean {
+  return existsSync(dir) && statSync(dir).isDirectory() && existsSync(join(dir, "DESIGN.md"))
+}
+
+function resolveDesignDir(nameInput?: string): string | null {
+  const name = normalizeDesignName(nameInput || activeDesign())
+  const userDir = join(DESIGNS_DIR, name)
+  if (designDirHasPackage(userDir)) return userDir
+
+  const bundledDir = join(SEED_DIR, name)
+  if (designDirHasPackage(bundledDir)) return bundledDir
+
+  return null
+}
+
+function readDesignsFromDir(root: string): Map<string, DesignInfo> {
+  const designs = new Map<string, DesignInfo>()
+  if (!existsSync(root)) return designs
+
+  for (const entry of readdirSync(root).sort()) {
+    const dir = join(root, entry)
+    if (!designDirHasPackage(dir)) continue
+    const info = parseDesignFile(join(dir, "DESIGN.md"))
+    if (info) designs.set(entry, info)
+  }
+  return designs
+}
+
+/** List available designs, sorted by name. User designs override bundled designs with the same name. Internal designs are hidden by default. */
 export function listDesigns(options: ListDesignsOptions = {}): DesignInfo[] {
-  if (!existsSync(DESIGNS_DIR)) return []
-  const results: DesignInfo[] = []
   const includeInternal = options.includeInternal ?? false
+  const available = readDesignsFromDir(SEED_DIR)
 
-  for (const entry of readdirSync(DESIGNS_DIR).sort()) {
-    const dir = join(DESIGNS_DIR, entry)
-    if (!statSync(dir).isDirectory()) continue
-    const mdPath = join(dir, "DESIGN.md")
-    if (!existsSync(mdPath)) continue
-    const info = parseDesignFile(mdPath)
-    if (info && (includeInternal || !info.internal)) results.push(info)
+  for (const [entry, info] of readDesignsFromDir(DESIGNS_DIR)) {
+    available.set(entry, info)
   }
-  return results
+
+  return [...available.values()]
+    .filter((info) => includeInternal || !info.internal)
+    .sort((a, b) => a.name.localeCompare(b.name))
 }
 
 /** Get the name of the currently active design. */
@@ -187,11 +210,12 @@ export function activateDesign(name: string): void {
 
 /** Get the skill text body from a design's DESIGN.md. */
 export function getDesignSkillMd(name?: string): string {
-  const designName = name || activeDesign()
-  const mdPath = join(DESIGNS_DIR, designName, "DESIGN.md")
-  if (!existsSync(mdPath)) {
+  const designName = normalizeDesignName(name || activeDesign())
+  const designDir = resolveDesignDir(designName)
+  if (!designDir) {
     throw new Error(`Design '${designName}' is not installed`)
   }
+  const mdPath = join(designDir, "DESIGN.md")
   const info = parseDesignFile(mdPath)
   if (!info) {
     throw new Error(`Failed to parse DESIGN.md for '${designName}'`)
@@ -202,9 +226,8 @@ export function getDesignSkillMd(name?: string): string {
 /** Resolve a design's preview.html path. Throws if the design is not installed. */
 export function resolveDesignPreview(name?: string): DesignPreviewInfo {
   const designName = normalizeDesignName(name || activeDesign())
-  const designDir = join(DESIGNS_DIR, designName)
-  const mdPath = join(designDir, "DESIGN.md")
-  if (!existsSync(designDir) || !existsSync(mdPath)) {
+  const designDir = resolveDesignDir(designName)
+  if (!designDir) {
     throw new Error(`Design '${designName}' is not installed`)
   }
 
@@ -388,12 +411,15 @@ function hasFixedSizeCssRule(html: string, className: "slide-canvas"): boolean {
 /** Validate a local design package for the minimum Revela design contract. */
 export function validateDesignPackage(nameInput: string): ValidateDesignPackageResult {
   let name = nameInput
+  let hasValidName = true
   try {
     name = normalizeDesignName(nameInput)
   } catch {
+    hasValidName = false
     // validateDesignPackageAt records the invalid-name error.
   }
-  return validateDesignPackageAt(nameInput, join(DESIGNS_DIR, name))
+  const dir = hasValidName ? resolveDesignDir(name) || join(DESIGNS_DIR, name) : join(DESIGNS_DIR, name)
+  return validateDesignPackageAt(nameInput, dir)
 }
 
 function validateDesignPackageAt(nameInput: string, dir: string): ValidateDesignPackageResult {
@@ -493,6 +519,25 @@ export interface DesignSections {
   hasMarkers: boolean
 }
 
+export interface DesignInventoryLayout {
+  name: string
+  qa: boolean
+  description: string
+}
+
+export interface DesignInventoryComponent {
+  name: string
+  description: string
+}
+
+export interface DesignInventory {
+  name: string
+  sections: string[]
+  layouts: DesignInventoryLayout[]
+  components: DesignInventoryComponent[]
+  hasMarkers: boolean
+}
+
 /**
  * Parse a DESIGN.md body (no frontmatter) into sections, layouts, and components
  * using the three-layer HTML comment marker convention:
@@ -566,7 +611,7 @@ export function generateComponentIndex(components: Record<string, string>): stri
     "|---|---|",
     ...rows,
     "",
-    "_Use `revela-designs` tool with `action: \"read\"` and `component: \"<name>\"` to get full CSS/HTML for any component._",
+    "_Use `revela_design_read_component` with `component: \"<name>\"` to get full CSS/HTML for any component._",
   ].join("\n")
 }
 
@@ -598,10 +643,47 @@ export function generateLayoutIndex(layouts: Record<string, LayoutInfo>): string
     "|---|---|---|",
     ...rows,
     "",
-    "_Use `revela-designs` tool with `action: \"read\"` and `layout: \"<name>\"` to get full HTML/CSS for any layout._",
+    "_Use `revela_design_read_layout` with `layout: \"<name>\"` to get full HTML/CSS for any layout._",
   ].join("\n")
 }
 
+export function getDesignInventory(designName?: string): DesignInventory {
+  const name = normalizeDesignName(designName || activeDesign())
+  const designDir = resolveDesignDir(name)
+  if (!designDir) {
+    throw new Error(`Design '${name}' is not installed`)
+  }
+  const mdPath = join(designDir, "DESIGN.md")
+  const text = readFileSync(mdPath, "utf-8")
+  const { body } = parseFrontmatter(text)
+  const { sections, layouts, components, hasMarkers } = parseDesignSections(body)
+
+  return {
+    name,
+    sections: Object.keys(sections),
+    layouts: Object.entries(layouts).map(([layoutName, layout]) => ({
+      name: layoutName,
+      qa: layout.qa,
+      description: designBlockDescription(layout.content),
+    })),
+    components: Object.entries(components).map(([componentName, content]) => ({
+      name: componentName,
+      description: designBlockDescription(content),
+    })),
+    hasMarkers,
+  }
+}
+
+function designBlockDescription(body: string): string {
+  const firstLine = body
+    .split("\n")
+    .map((line) => line.trim())
+    .find((line) => line && !line.startsWith("<!--") && !line.startsWith("```"))
+  return firstLine
+    ? firstLine.replace(/^#+\s*/, "").replace(/\(.*?\)/, "").trim()
+    : ""
+}
+
 /**
  * Get the raw text of one or more named layouts from a DESIGN.md.
  * @param layoutNames - Comma-separated layout names or an array.
@@ -611,11 +693,12 @@ export function getDesignLayout(
   layoutNames: string | string[],
   designName?: string,
 ): string {
-  const name = designName || activeDesign()
-  const mdPath = join(DESIGNS_DIR, name, "DESIGN.md")
-  if (!existsSync(mdPath)) {
+  const name = normalizeDesignName(designName || activeDesign())
+  const designDir = resolveDesignDir(name)
+  if (!designDir) {
     throw new Error(`Design '${name}' is not installed`)
   }
+  const mdPath = join(designDir, "DESIGN.md")
   const text = readFileSync(mdPath, "utf-8")
   const { body } = parseFrontmatter(text)
   const { layouts, hasMarkers } = parseDesignSections(body)
@@ -644,11 +727,12 @@ export function getDesignLayout(
  * Throws if the design is not installed or the section doesn't exist.
  */
 export function getDesignSection(sectionName: string, designName?: string): string {
-  const name = designName || activeDesign()
-  const mdPath = join(DESIGNS_DIR, name, "DESIGN.md")
-  if (!existsSync(mdPath)) {
+  const name = normalizeDesignName(designName || activeDesign())
+  const designDir = resolveDesignDir(name)
+  if (!designDir) {
     throw new Error(`Design '${name}' is not installed`)
   }
+  const mdPath = join(designDir, "DESIGN.md")
   const text = readFileSync(mdPath, "utf-8")
   const { body } = parseFrontmatter(text)
   const { sections, hasMarkers } = parseDesignSections(body)
@@ -671,11 +755,12 @@ export function getDesignComponent(
   componentNames: string | string[],
   designName?: string,
 ): string {
-  const name = designName || activeDesign()
-  const mdPath = join(DESIGNS_DIR, name, "DESIGN.md")
-  if (!existsSync(mdPath)) {
+  const name = normalizeDesignName(designName || activeDesign())
+  const designDir = resolveDesignDir(name)
+  if (!designDir) {
     throw new Error(`Design '${name}' is not installed`)
   }
+  const mdPath = join(designDir, "DESIGN.md")
   const text = readFileSync(mdPath, "utf-8")
   const { body } = parseFrontmatter(text)
   const { components, hasMarkers } = parseDesignSections(body)
@@ -742,8 +827,7 @@ export async function installDesign(
 // ---------------------------------------------------------------------------
 
 function designExists(name: string): boolean {
-  const dir = join(DESIGNS_DIR, name)
-  return existsSync(dir) && existsSync(join(dir, "DESIGN.md"))
+  return resolveDesignDir(name) !== null
 }
 
 function installFromPath(srcPath: string, name?: string): string {
@@ -814,13 +898,13 @@ export interface DesignClassVocabulary {
  * Falls back to UNIVERSAL_CLASSES-only when the design has no markers.
  */
 export function extractDesignClasses(designName?: string): DesignClassVocabulary {
-  const name = designName || activeDesign()
-  const mdPath = join(DESIGNS_DIR, name, "DESIGN.md")
-
-  if (!existsSync(mdPath)) {
+  const name = normalizeDesignName(designName || activeDesign())
+  const designDir = resolveDesignDir(name)
+  if (!designDir) {
     return { classes: new Set(UNIVERSAL_CLASSES), prefixExemptions: DEFAULT_PREFIX_EXEMPTIONS }
   }
 
+  const mdPath = join(designDir, "DESIGN.md")
   const raw = readFileSync(mdPath, "utf-8")
   const { body } = parseFrontmatter(raw)
   const { sections, layouts, components, hasMarkers } = parseDesignSections(body)

package/lib/document-materials/extract.ts

@@ -58,6 +58,7 @@ export type DocumentMaterialsResult = {
   cache_dir?: string
   manifest_path?: string
   text_path?: string
+  read_view_path?: string
   images?: DocumentMaterial[]
   skipped_assets?: SkippedAsset[]
   slides?: PptxSlide[]
@@ -74,6 +75,7 @@ type CachedManifest = {
   cache_dir: string
   manifest_path: string
   text_path: string
+  read_view_path?: string
   images: DocumentMaterial[]
   skipped_assets: SkippedAsset[]
   slides: PptxSlide[]
@@ -157,6 +159,145 @@ function materialPath(cacheDir: string, workspaceDir: string, ...segments: strin
   return workspaceRelative(join(cacheDir, ...segments), workspaceDir)
 }
 
+function buildReadView(input: {
+  source: string
+  type: SupportedType
+  fingerprint: string
+  text: string
+  manifestPath: string
+  textPath: string
+  images: DocumentMaterial[]
+  skippedAssets: SkippedAsset[]
+  tables: DocumentMaterial[]
+  slides: PptxSlide[] | undefined
+}): string {
+  const lines = [
+    `# Extracted Material: ${basename(input.source)}`,
+    "",
+    "## Source",
+    "",
+    `- sourcePath: ${input.source}`,
+    `- type: ${input.type}`,
+    `- fingerprint: ${input.fingerprint}`,
+    `- manifestPath: ${input.manifestPath}`,
+    `- textPath: ${input.textPath}`,
+    "",
+    "## Text",
+    "",
+    input.text.trim() || "No text extracted.",
+    "",
+    "## Extracted Images",
+    "",
+  ]
+
+  if (input.images.length === 0) lines.push("- None")
+  else {
+    for (const image of input.images) {
+      const parts = [
+        image.page_or_slide ? `page_or_slide: ${image.page_or_slide}` : null,
+        `source_ref: ${image.source_ref}`,
+        image.note ? `note: ${image.note}` : null,
+      ].filter(Boolean).join("; ")
+      lines.push(`- ${image.path}${parts ? ` (${parts})` : ""}`)
+    }
+  }
+
+  if (input.skippedAssets.length > 0) {
+    lines.push("", "## Skipped Or Unmapped Assets", "")
+    for (const asset of input.skippedAssets) {
+      const parts = [
+        asset.page_or_slide ? `page_or_slide: ${asset.page_or_slide}` : null,
+        `reason: ${asset.reason}`,
+        asset.kind ? `kind: ${asset.kind}` : null,
+      ].filter(Boolean).join("; ")
+      lines.push(`- ${asset.source_ref}${parts ? ` (${parts})` : ""}`)
+    }
+  }
+
+  if (input.tables.length > 0) {
+    lines.push("", "## Extracted Tables", "")
+    for (const table of input.tables) lines.push(`- ${table.path} (${table.note ?? table.source_ref})`)
+  }
+
+  if (input.slides?.length) {
+    lines.push("", "## Slide Structure", "")
+    for (const slide of input.slides) {
+      const textCount = slide.elements.filter((element) => element.kind === "text").length
+      const imageCount = slide.elements.filter((element) => element.kind === "image").length
+      const shapeCount = slide.elements.filter((element) => element.kind === "shape").length
+      lines.push(`- ${slide.slide}: ${textCount} text, ${imageCount} image, ${shapeCount} shape`)
+    }
+  }
+
+  lines.push(
+    "",
+    "## Intake Rules",
+    "",
+    "- Treat this extracted material as source context until a material review records what was considered.",
+    "- Do not treat extracted images as interpreted evidence unless an explicit image review or user-provided meaning exists.",
+    "- Canonical evidence still requires source trace, quote/snippet, support scope, unsupported scope, caveat, strength, and relations in `revela-narrative/`.",
+  )
+
+  return lines.join("\n")
+}
+
+function writeReadView(input: {
+  cacheDir: string
+  workspaceDir: string
+  source: string
+  type: SupportedType
+  fingerprint: string
+  text: string
+  manifestPath: string
+  textPath: string
+  images: DocumentMaterial[]
+  skippedAssets: SkippedAsset[]
+  tables: DocumentMaterial[]
+  slides?: PptxSlide[]
+}): string {
+  const readViewPath = join(input.cacheDir, "read.md")
+  writeFileSync(readViewPath, buildReadView({
+    source: input.source,
+    type: input.type,
+    fingerprint: input.fingerprint,
+    text: input.text,
+    manifestPath: input.manifestPath,
+    textPath: input.textPath,
+    images: input.images,
+    skippedAssets: input.skippedAssets,
+    tables: input.tables,
+    slides: input.slides,
+  }), "utf-8")
+  return workspaceRelative(readViewPath, input.workspaceDir)
+}
+
+function ensureCachedReadView(
+  manifest: CachedManifest,
+  cacheDir: string,
+  workspaceDir: string,
+): string {
+  const existing = manifest.read_view_path
+  if (existing && existsSync(join(workspaceDir, existing))) return existing
+
+  const text = existsSync(join(workspaceDir, manifest.text_path))
+    ? readFileSync(join(workspaceDir, manifest.text_path), "utf-8").replace(/^\[Extracted from: .*?\]\n\n/, "")
+    : ""
+  return writeReadView({
+    cacheDir,
+    workspaceDir,
+    source: manifest.source,
+    type: manifest.type,
+    fingerprint: manifest.fingerprint,
+    text,
+    manifestPath: manifest.manifest_path,
+    textPath: manifest.text_path,
+    images: manifest.images,
+    skippedAssets: manifest.skipped_assets,
+    tables: manifest.tables,
+    slides: manifest.slides,
+  })
+}
+
 function updateDecksSourceMaterialIndex(
   workspaceDir: string,
   filePath: string,
@@ -716,6 +857,7 @@ async function processPdfFile(filePath: string, workspaceDir: string): Promise<D
 
   if (existsSync(manifestPath)) {
     const manifest = JSON.parse(readFileSync(manifestPath, "utf-8")) as CachedManifest
+    const readViewPath = ensureCachedReadView(manifest, cacheDir, workspaceDir)
     return {
       status: "processed",
       cache_status: "hit",
@@ -724,6 +866,7 @@ async function processPdfFile(filePath: string, workspaceDir: string): Promise<D
       cache_dir: manifest.cache_dir,
       manifest_path: manifest.manifest_path,
       text_path: manifest.text_path,
+      read_view_path: readViewPath,
       images: manifest.images,
       skipped_assets: manifest.skipped_assets,
       slides: manifest.slides,
@@ -740,6 +883,22 @@ async function processPdfFile(filePath: string, workspaceDir: string): Promise<D
   writeFileSync(textPath, `[Extracted from: ${basename(filePath)}]\n\n${text}`, "utf-8")
 
   const images = await extractPdfImages(buf, cacheDir, workspaceDir)
+  const relativeManifestPath = workspaceRelative(manifestPath, workspaceDir)
+  const relativeTextPath = workspaceRelative(textPath, workspaceDir)
+  const readViewPath = writeReadView({
+    cacheDir,
+    workspaceDir,
+    source: relativeSource,
+    type: "pdf",
+    fingerprint,
+    text,
+    manifestPath: relativeManifestPath,
+    textPath: relativeTextPath,
+    images,
+    skippedAssets: [],
+    tables: [],
+    slides: [],
+  })
 
   const result: DocumentMaterialsResult = {
     status: "processed",
@@ -747,8 +906,9 @@ async function processPdfFile(filePath: string, workspaceDir: string): Promise<D
     source: relativeSource,
     type: "pdf",
     cache_dir: workspaceRelative(cacheDir, workspaceDir),
-    manifest_path: workspaceRelative(manifestPath, workspaceDir),
-    text_path: workspaceRelative(textPath, workspaceDir),
+    manifest_path: relativeManifestPath,
+    text_path: relativeTextPath,
+    read_view_path: readViewPath,
     images,
     skipped_assets: [],
     slides: [],
@@ -762,6 +922,7 @@ async function processPdfFile(filePath: string, workspaceDir: string): Promise<D
     cache_dir: result.cache_dir!,
     manifest_path: result.manifest_path!,
     text_path: result.text_path!,
+    read_view_path: result.read_view_path,
     images: result.images ?? [],
     skipped_assets: [],
     slides: [],
@@ -780,6 +941,7 @@ async function processOfficeFile(filePath: string, workspaceDir: string, type: S
 
   if (existsSync(manifestPath)) {
     const manifest = JSON.parse(readFileSync(manifestPath, "utf-8")) as CachedManifest
+    const readViewPath = ensureCachedReadView(manifest, cacheDir, workspaceDir)
     return {
       status: "processed",
       cache_status: "hit",
@@ -788,6 +950,7 @@ async function processOfficeFile(filePath: string, workspaceDir: string, type: S
       cache_dir: manifest.cache_dir,
       manifest_path: manifest.manifest_path,
       text_path: manifest.text_path,
+      read_view_path: readViewPath,
       images: manifest.images,
       skipped_assets: manifest.skipped_assets,
       slides: manifest.slides,
@@ -821,6 +984,24 @@ async function processOfficeFile(filePath: string, workspaceDir: string, type: S
   const slides = type === "pptx"
     ? extractPptxSlides(files, images, pptxAssets!.skipped_assets)
     : undefined
+  const relativeManifestPath = workspaceRelative(manifestPath, workspaceDir)
+  const relativeTextPath = workspaceRelative(textPath, workspaceDir)
+  const tables = extractTables(type, relativeTextPath)
+  const skippedAssets = pptxAssets?.skipped_assets ?? []
+  const readViewPath = writeReadView({
+    cacheDir,
+    workspaceDir,
+    source: relativeSource,
+    type,
+    fingerprint,
+    text,
+    manifestPath: relativeManifestPath,
+    textPath: relativeTextPath,
+    images,
+    skippedAssets,
+    tables,
+    slides,
+  })
 
   const result: DocumentMaterialsResult = {
     status: "processed",
@@ -828,12 +1009,13 @@ async function processOfficeFile(filePath: string, workspaceDir: string, type: S
     source: relativeSource,
     type,
     cache_dir: workspaceRelative(cacheDir, workspaceDir),
-    manifest_path: workspaceRelative(manifestPath, workspaceDir),
-    text_path: workspaceRelative(textPath, workspaceDir),
+    manifest_path: relativeManifestPath,
+    text_path: relativeTextPath,
+    read_view_path: readViewPath,
     images,
-    skipped_assets: pptxAssets?.skipped_assets ?? [],
+    skipped_assets: skippedAssets,
     slides,
-    tables: extractTables(type, workspaceRelative(textPath, workspaceDir)),
+    tables,
   }
 
   const manifest: CachedManifest = {
@@ -843,6 +1025,7 @@ async function processOfficeFile(filePath: string, workspaceDir: string, type: S
     cache_dir: result.cache_dir!,
     manifest_path: result.manifest_path!,
     text_path: result.text_path!,
+    read_view_path: result.read_view_path,
     images: result.images ?? [],
     skipped_assets: result.skipped_assets ?? [],
     slides: result.slides ?? [],