@cyber-dash-tech/revela 0.17.22 → 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/runtime/index.ts

@@ -6,6 +6,9 @@ import {
   activateDesign,
   createDesignDraftPackage,
   createDesignPackage,
+  getDesignComponent,
+  getDesignInventory,
+  getDesignLayout,
   getDesignSection,
   getDesignSkillMd,
   installDesignDraftPackage,
@@ -59,6 +62,20 @@ export interface RuntimeDesignReadInput {
   section?: string
 }
 
+export interface RuntimeDesignInventoryInput {
+  name?: string
+}
+
+export interface RuntimeDesignLayoutReadInput {
+  name?: string
+  layout: string | string[]
+}
+
+export interface RuntimeDesignComponentReadInput {
+  name?: string
+  component: string | string[]
+}
+
 export interface RuntimeDesignCreateInput {
   name: string
   base?: string
@@ -212,7 +229,6 @@ export async function reviewDeckOpen(input: ReviewDeckOpenInput) {
 }
 
 export function designList() {
-  seedBuiltinDesigns()
   return {
     ok: true,
     activeDesign: activeDesign(),
@@ -226,7 +242,6 @@ export function designList() {
 }
 
 export function designRead(input: RuntimeDesignReadInput = {}) {
-  seedBuiltinDesigns()
   const name = input.name || activeDesign()
   if (input.section) {
     const markdown = getDesignSection(input.section, name)
@@ -246,6 +261,33 @@ export function designRead(input: RuntimeDesignReadInput = {}) {
   }
 }
 
+export function designInventory(input: RuntimeDesignInventoryInput = {}) {
+  return {
+    ok: true,
+    ...getDesignInventory(input.name || activeDesign()),
+  }
+}
+
+export function designReadLayout(input: RuntimeDesignLayoutReadInput) {
+  const name = input.name || activeDesign()
+  return {
+    ok: true,
+    name,
+    layout: input.layout,
+    markdown: getDesignLayout(input.layout, name),
+  }
+}
+
+export function designReadComponent(input: RuntimeDesignComponentReadInput) {
+  const name = input.name || activeDesign()
+  return {
+    ok: true,
+    name,
+    component: input.component,
+    markdown: getDesignComponent(input.component, name),
+  }
+}
+
 export function designCreate(input: RuntimeDesignCreateInput) {
   seedBuiltinDesigns()
   return createDesignPackage({
@@ -258,7 +300,6 @@ export function designCreate(input: RuntimeDesignCreateInput) {
 }
 
 export function designValidate(input: RuntimeNameInput) {
-  seedBuiltinDesigns()
   return validateDesignPackage(requiredName(input, "design"))
 }
 
@@ -296,7 +337,6 @@ export interface DesignRulesReadinessResult {
 const DESIGN_RULES_MARKER_TTL_MS = 8 * 60 * 60 * 1000
 
 export function checkDesignRulesReadiness(input: RuntimeWorkspaceInput = {}): DesignRulesReadinessResult {
-  seedBuiltinDesigns()
   const workspaceRoot = root(input.workspaceRoot)
   const design = activeDesign()
   const rules = getDesignSection("rules", design)

package/package.json

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

package/plugins/revela/.mcp.json

@@ -2,7 +2,7 @@
   "mcpServers": {
     "revela": {
       "command": "npx",
-      "args": ["-y", "@cyber-dash-tech/revela@0.17.22", "mcp"]
+      "args": ["-y", "@cyber-dash-tech/revela@0.17.23", "mcp"]
     }
   }
 }

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

@@ -19,6 +19,9 @@ type RuntimeModule = {
   exportPptx(input: any): Promise<any>
   designList(): any
   designRead(input?: any): any
+  designInventory(input?: any): any
+  designReadLayout(input: any): any
+  designReadComponent(input: any): any
   designActivate(input: any): any
   designCreate(input: any): any
   designValidate(input: any): any
@@ -125,6 +128,29 @@ const tools = [
       section: stringProp("Optional design section, such as rules, foundation, or chart-rules."),
     }),
   },
+  {
+    name: "revela_design_inventory",
+    description: "List the active or requested Revela design sections, layouts, and components.",
+    inputSchema: objectSchema({
+      name: stringProp("Optional design name."),
+    }),
+  },
+  {
+    name: "revela_design_read_layout",
+    description: "Read one or more layout blocks from the active or requested Revela design.",
+    inputSchema: objectSchema({
+      name: stringProp("Optional design name."),
+      layout: stringOrArrayProp("Layout name, comma-separated names, or an array of layout names."),
+    }, ["layout"]),
+  },
+  {
+    name: "revela_design_read_component",
+    description: "Read one or more component blocks from the active or requested Revela design.",
+    inputSchema: objectSchema({
+      name: stringProp("Optional design name."),
+      component: stringOrArrayProp("Component name, comma-separated names, or an array of component names."),
+    }, ["component"]),
+  },
   {
     name: "revela_design_activate",
     description: "Activate a Revela design for future deck planning and artifact generation.",
@@ -394,6 +420,9 @@ async function callTool(name: string, args: any): Promise<any> {
   if (name === "revela_export_pptx") return r.exportPptx(args)
   if (name === "revela_design_list") return r.designList()
   if (name === "revela_design_read") return r.designRead(args)
+  if (name === "revela_design_inventory") return r.designInventory(args)
+  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_design_create") return r.designCreate(args)
   if (name === "revela_design_validate") return r.designValidate(args)
@@ -458,6 +487,16 @@ function arrayProp(description: string) {
   return { type: "array", items: { type: "string" }, description }
 }
 
+function stringOrArrayProp(description: string) {
+  return {
+    anyOf: [
+      { type: "string" },
+      { type: "array", items: { type: "string" } },
+    ],
+    description,
+  }
+}
+
 function arrayObjectProp(description: string) {
   return {
     type: "array",

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

@@ -11,11 +11,13 @@ Use this skill when the user asks about Revela designs or when generating deck H
 
 1. Call `revela_design_list` to inspect installed designs.
 2. Call `revela_design_read` with `section: "rules"` before writing or patching `decks/*.html`; this records the Codex hook context required for deck writes.
-3. When the user asks to switch designs for future work, call `revela_design_activate` with the requested design name, then read the active design again.
-4. For one-off deck generation with a requested design, read that design by name and pass `designName` to `revela_create_deck_foundation` without changing active design unless the user asked to switch.
-5. Use the current simplified built-in design grammar: `box`, `text-panel`, `media`, `echart-panel`, `data-table`, `steps`, `roadmap-horizontal`, `roadmap-vertical`, `hero`, `stat-card`, `quote`, `toc`, `page-number`, and `brand-watermark`.
-6. Fetch chart/design guidance before creating ECharts or complex layouts.
-7. Do not invent unsupported component names.
+3. Call `revela_design_inventory` before authoring or repairing `deck-plan/` so planned layout/component names come from the active design.
+4. Read required details with `revela_design_read_layout` and `revela_design_read_component` before writing slide HTML that uses those layouts/components.
+5. When the user asks to switch designs for future work, call `revela_design_activate` with the requested design name, then read the active design again.
+6. For one-off deck generation with a requested design, read that design by name, call `revela_design_inventory` with that name, and pass `designName` to `revela_create_deck_foundation` without changing active design unless the user asked to switch.
+7. Use the current simplified built-in design grammar: `box`, `text-panel`, `media`, `echart-panel`, `data-table`, `steps`, `roadmap-horizontal`, `roadmap-vertical`, `hero`, `stat-card`, `quote`, `toc`, `page-number`, and `brand-watermark`.
+8. Fetch chart/design guidance before creating ECharts or complex layouts.
+9. Do not invent unsupported component names.
 
 Deck HTML must keep exactly one direct `.slide-canvas` child inside every `<section class="slide" ...>`; place `.page` or layout containers inside `.slide-canvas`, not directly under `.slide`.
 

package/plugins/revela/skills/revela-make-deck/SKILL.md

@@ -18,15 +18,16 @@ Use this skill when the user asks to make, generate, or update a Revela deck.
 
 1. Call `revela_compile_narrative` and `revela_markdown_qa`.
 2. Report narrative and Markdown diagnostics, but treat only malformed/unsafe files and technical artifact validity as hard blockers.
-3. Call `revela_read_deck_plan` as the required deck-plan preflight before any HTML generation.
-4. If `deck-plan/` is missing or incomplete, author or repair `deck-plan/index.md` and `deck-plan/slides/*.md` before calling `revela_create_deck_foundation`.
-5. Report deck-plan diagnostics before artifact generation, including stale narrative hashes, missing slide projections, missing evidence trace, caveats, or malformed plan files.
-6. Do not start HTML generation from narrative alone unless the user explicitly asks for a throwaway diagnostic smoke deck.
-7. For new HTML files, call `revela_create_deck_foundation`.
-8. Read active design guidance with `revela_design_list` and `revela_design_read` using `section: "rules"` before writing `decks/*.html`; fetch layouts/components/chart rules as needed. If the user asks to switch designs persistently, call `revela_design_activate`; if they ask for a one-off design, read that design by name and pass `designName` to `revela_create_deck_foundation`.
-9. Patch slides into the foundation between Revela slide markers. Preserve positive 1-based `data-slide-index` values. Every slide must use `<section class="slide" ...>` with exactly one direct `.slide-canvas` child.
-10. Generate chapter by chapter. Keep the HTML valid after each write.
-11. After every HTML write, call `revela_run_deck_qa` and repair hard errors before review or export.
+3. Call `revela_design_list`, `revela_design_read` using `section: "rules"`, and `revela_design_inventory` before authoring or repairing `deck-plan/`; deck-plan layout/component names must come from the selected design inventory.
+4. Call `revela_read_deck_plan` as the required deck-plan preflight before any HTML generation.
+5. If `deck-plan/` is missing or incomplete, author or repair `deck-plan/index.md` and `deck-plan/slides/*.md` before calling `revela_create_deck_foundation`; use only inventory-listed layouts/components in slide frontmatter and visual intent.
+6. Report deck-plan diagnostics before artifact generation, including stale narrative hashes, missing slide projections, missing evidence trace, caveats, malformed plan files, or layout/component names outside the active design inventory.
+7. Do not start HTML generation from narrative alone unless the user explicitly asks for a throwaway diagnostic smoke deck.
+8. For new HTML files, call `revela_create_deck_foundation`.
+9. Before patching slide HTML, read the specific layouts/components used by the deck plan with `revela_design_read_layout` and `revela_design_read_component`; fetch `section: "chart-rules"` and the `echart-panel` component before creating or changing ECharts. If the user asks to switch designs persistently, call `revela_design_activate`; if they ask for a one-off design, read that design by name, call `revela_design_inventory` with that name, and pass `designName` to `revela_create_deck_foundation`.
+10. Patch slides into the foundation between Revela slide markers. Preserve positive 1-based `data-slide-index` values. Every slide must use `<section class="slide" ...>` with exactly one direct `.slide-canvas` child.
+11. Generate chapter by chapter. Keep the HTML valid after each write.
+12. After every HTML write, call `revela_run_deck_qa` and repair hard errors before review or export.
 
 ## Generated Visual Assets