@cyber-dash-tech/revela 0.18.9 → 0.18.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-723%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-727%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" />
@@ -34,7 +34,7 @@ To install globally, add the same entry to `~/.config/opencode/opencode.json`.
 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.18.9 mcp` to start the MCP server.
+- Your environment must be able to run `npx`; Revela uses `npx -y @cyber-dash-tech/revela@0.18.11 mcp` to start the MCP server.
 - For interactive Review Apply actions, `codex exec` must also work because the Review UI uses it after saved comments are applied.
 
 Optional preflight:
@@ -55,11 +55,11 @@ npm_config_cache=/tmp/revela-npm-cache bun run smoke:mcp-pack
 Install Revela through the Codex Git marketplace:
 
 ```bash
-codex plugin marketplace add https://github.com/cyber-dash-tech/revela --ref v0.18.9
+codex plugin marketplace add https://github.com/cyber-dash-tech/revela --ref v0.18.11
 codex plugin add revela@revela
 ```
 
-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.18.9 mcp` so npm can fetch the published package and its dependencies.
+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.18.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.
 

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-723%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-727%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" />
@@ -34,7 +34,7 @@ Revela 可在 [OpenCode](https://opencode.ai) 和 Codex 中使用，把来源材
 环境要求：
 
 - 需要已安装 Codex CLI，并且 shell 中可以执行 `codex`。
-- 环境中需要可以执行 `npx`；Revela 会用 `npx -y @cyber-dash-tech/revela@0.18.9 mcp` 启动 MCP server。
+- 环境中需要可以执行 `npx`；Revela 会用 `npx -y @cyber-dash-tech/revela@0.18.11 mcp` 启动 MCP server。
 - 如果使用 Review UI 的 Apply，需要 `codex exec` 可用；评论会先保存，点击 Apply 后才执行修复。
 
 可选的安装前检查：
@@ -55,11 +55,11 @@ npm_config_cache=/tmp/revela-npm-cache bun run smoke:mcp-pack
 通过 Codex Git marketplace 安装 Revela：
 
 ```bash
-codex plugin marketplace add https://github.com/cyber-dash-tech/revela --ref v0.18.9
+codex plugin marketplace add https://github.com/cyber-dash-tech/revela --ref v0.18.11
 codex plugin add revela@revela
 ```
 
-Git marketplace 安装的是 Codex plugin 壳、skills、hooks 和 MCP 配置。Codex 第一次启动 Revela MCP server 时，会运行 `npx -y @cyber-dash-tech/revela@0.18.9 mcp`，由 npm 获取已发布 package 及其 dependencies。
+Git marketplace 安装的是 Codex plugin 壳、skills、hooks 和 MCP 配置。Codex 第一次启动 Revela MCP server 时，会运行 `npx -y @cyber-dash-tech/revela@0.18.11 mcp`，由 npm 获取已发布 package 及其 dependencies。
 
 不需要在 Codex marketplace clone 里运行 `bun install`。
 

package/bin/revela.ts

@@ -32,6 +32,8 @@ else {
     else if (command === "design-use") result = runtime.designActivate(required(options, ["name"]))
     else if (command === "design-create") result = runtime.designCreate(required(options, ["name", "designMd", "previewHtml"]))
     else if (command === "design-validate") result = runtime.designValidate(required(options, ["name"]))
+    else if (command === "design-pack") result = runtime.designPack(required(options, ["name"]))
+    else if (command === "design-install-archive") result = runtime.designInstallArchive(required(options, ["archivePath"]))
     else if (command === "domain-list") result = runtime.domainList()
     else if (command === "domain-read") result = runtime.domainRead(options)
     else if (command === "domain-use") result = runtime.domainActivate(required(options, ["name"]))

package/lib/design/archive.ts

@@ -0,0 +1,167 @@
+import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "fs"
+import { basename, dirname, join, relative, resolve, sep } from "path"
+import { gunzipSync, gzipSync } from "zlib"
+
+export interface TarEntry {
+  path: string
+  bytes: Buffer
+  mode?: number
+  mtime?: number
+}
+
+const BLOCK_SIZE = 512
+
+export function writeTarArchive(entries: TarEntry[], targetPath: string, gzip: boolean): void {
+  const chunks: Buffer[] = []
+  for (const entry of entries) {
+    const normalized = safeArchivePath(entry.path)
+    const bytes = entry.bytes
+    const header = Buffer.alloc(BLOCK_SIZE, 0)
+    writeString(header, 0, 100, normalized)
+    writeOctal(header, 100, 8, entry.mode ?? 0o644)
+    writeOctal(header, 108, 8, 0)
+    writeOctal(header, 116, 8, 0)
+    writeOctal(header, 124, 12, bytes.byteLength)
+    writeOctal(header, 136, 12, Math.floor(entry.mtime ?? Date.now() / 1000))
+    header.fill(0x20, 148, 156)
+    header[156] = "0".charCodeAt(0)
+    writeString(header, 257, 6, "ustar")
+    writeString(header, 263, 2, "00")
+    const checksum = header.reduce((sum, value) => sum + value, 0)
+    writeOctal(header, 148, 8, checksum)
+    chunks.push(header, bytes)
+    const remainder = bytes.byteLength % BLOCK_SIZE
+    if (remainder !== 0) chunks.push(Buffer.alloc(BLOCK_SIZE - remainder, 0))
+  }
+  chunks.push(Buffer.alloc(BLOCK_SIZE * 2, 0))
+  const tar = Buffer.concat(chunks as any)
+  mkdirSync(dirname(targetPath), { recursive: true })
+  writeFileSync(targetPath, (gzip ? gzipSync(tar as any) : tar) as any)
+}
+
+export function readTarArchive(archivePath: string): TarEntry[] {
+  const raw = readFileSync(archivePath)
+  const bytes = (archivePath.endsWith(".gz") || archivePath.endsWith(".tgz") ? gunzipSync(raw as any) : raw) as Buffer
+  const entries: TarEntry[] = []
+  let offset = 0
+  while (offset + BLOCK_SIZE <= bytes.byteLength) {
+    const header = bytes.subarray(offset, offset + BLOCK_SIZE)
+    offset += BLOCK_SIZE
+    if (header.every((value) => value === 0)) break
+    const rawPath = readString(header, 0, 100)
+    const size = readOctal(header, 124, 12)
+    const type = String.fromCharCode(header[156] || 0)
+    if (type === "5") {
+      const dirPath = rawPath.replace(/\/+$/, "")
+      if (dirPath) safeArchivePath(dirPath)
+      offset += paddedSize(size)
+      continue
+    }
+    const path = safeArchivePath(rawPath)
+    if (type === "2") throw new Error(`Archive symlinks are not supported: ${path}`)
+    if (type !== "0" && type !== "\0" && type !== "") {
+      offset += paddedSize(size)
+      continue
+    }
+    if (offset + size > bytes.byteLength) throw new Error(`Archive entry is truncated: ${path}`)
+    entries.push({ path, bytes: bytes.subarray(offset, offset + size), mode: readOctal(header, 100, 8), mtime: readOctal(header, 136, 12) })
+    offset += paddedSize(size)
+  }
+  return entries
+}
+
+export function collectDirectoryEntries(sourceDir: string, prefix = ""): TarEntry[] {
+  const root = resolve(sourceDir)
+  const entries: TarEntry[] = []
+  walk(root)
+  return entries.sort((a, b) => a.path.localeCompare(b.path))
+
+  function walk(dir: string): void {
+    for (const entry of readdirSync(dir).sort()) {
+      if (entry === ".DS_Store" || entry.startsWith(".")) continue
+      const abs = join(dir, entry)
+      const stat = lstatSync(abs)
+      if (stat.isSymbolicLink()) throw new Error(`Design archives cannot include symlinks: ${abs}`)
+      if (stat.isDirectory()) {
+        walk(abs)
+        continue
+      }
+      if (!stat.isFile()) continue
+      const rel = relative(root, abs).split(sep).join("/")
+      entries.push({
+        path: safeArchivePath(prefix ? `${prefix}/${rel}` : rel),
+        bytes: readFileSync(abs),
+        mode: stat.mode & 0o777,
+        mtime: Math.floor(stat.mtimeMs / 1000),
+      })
+    }
+  }
+}
+
+export function extractEntriesToDirectory(entries: TarEntry[], targetDir: string): string[] {
+  const root = resolve(targetDir)
+  if (existsSync(root)) rmSync(root, { recursive: true, force: true })
+  mkdirSync(root, { recursive: true })
+  const files: string[] = []
+  for (const entry of entries) {
+    const rel = safeArchivePath(entry.path)
+    const target = resolve(root, rel)
+    if (target !== root && !target.startsWith(root + sep)) throw new Error(`Archive path escapes target directory: ${entry.path}`)
+    mkdirSync(dirname(target), { recursive: true })
+    writeFileSync(target, entry.bytes as any)
+    files.push(rel)
+  }
+  return files.sort()
+}
+
+export function normalizePackageArchiveEntries(entries: TarEntry[]): TarEntry[] {
+  const files = entries.filter((entry) => entry.path && !entry.path.endsWith("/"))
+  if (files.some((entry) => basename(entry.path) === "DESIGN.md")) {
+    if (files.some((entry) => entry.path === "DESIGN.md")) return files
+    const top = commonTopLevel(files)
+    if (top && files.some((entry) => entry.path === `${top}/DESIGN.md`)) {
+      return files.map((entry) => ({ ...entry, path: entry.path.slice(top.length + 1) }))
+    }
+  }
+  throw new Error("No DESIGN.md found in design archive")
+}
+
+function commonTopLevel(entries: TarEntry[]): string | null {
+  const first = entries[0]?.path.split("/")[0]
+  if (!first || first === entries[0]?.path) return null
+  return entries.every((entry) => entry.path.startsWith(`${first}/`)) ? first : null
+}
+
+function safeArchivePath(input: string): string {
+  const normalized = input.replace(/\\/g, "/").replace(/^\.\/+/, "")
+  if (!normalized || normalized.startsWith("/") || normalized.includes("\0")) throw new Error(`Invalid archive path: ${input}`)
+  const parts = normalized.split("/")
+  if (parts.some((part) => !part || part === "." || part === "..")) throw new Error(`Invalid archive path: ${input}`)
+  if (Buffer.byteLength(normalized) > 100) throw new Error(`Archive path is too long for v1 tar support: ${normalized}`)
+  return normalized
+}
+
+function writeString(buffer: Buffer, offset: number, length: number, value: string): void {
+  buffer.write(value, offset, Math.min(length, Buffer.byteLength(value)), "utf8")
+}
+
+function readString(buffer: Buffer, offset: number, length: number): string {
+  const slice = buffer.subarray(offset, offset + length)
+  const end = slice.indexOf(0)
+  return slice.subarray(0, end === -1 ? length : end).toString("utf8").trim()
+}
+
+function writeOctal(buffer: Buffer, offset: number, length: number, value: number): void {
+  const text = value.toString(8).padStart(length - 1, "0").slice(0, length - 1)
+  buffer.write(text, offset, length - 1, "ascii")
+  buffer[offset + length - 1] = 0
+}
+
+function readOctal(buffer: Buffer, offset: number, length: number): number {
+  const text = readString(buffer, offset, length).replace(/\0/g, "").trim()
+  return text ? parseInt(text, 8) : 0
+}
+
+function paddedSize(size: number): number {
+  return Math.ceil(size / BLOCK_SIZE) * BLOCK_SIZE
+}

package/lib/design/designs.ts

@@ -9,6 +9,7 @@
 import {
   cpSync,
   existsSync,
+  lstatSync,
   mkdirSync,
   readdirSync,
   readFileSync,
@@ -16,9 +17,10 @@ import {
   statSync,
   writeFileSync,
 } from "fs"
-import { dirname, join, resolve, basename } from "path"
+import { dirname, join, resolve, basename, relative, sep } from "path"
 import { tmpdir } from "os"
 import { parseFrontmatter } from "../frontmatter"
+import { collectDirectoryEntries, extractEntriesToDirectory, normalizePackageArchiveEntries, readTarArchive, writeTarArchive } from "./archive"
 import {
   DESIGNS_DIR,
   DEFAULT_DESIGN,
@@ -50,6 +52,7 @@ export interface CreateDesignPackageArgs {
   base?: string
   designMd: string
   previewHtml: string
+  assets?: DesignPackageAssetInput[]
   overwrite?: boolean
 }
 
@@ -62,6 +65,7 @@ export interface CreateDesignPackageResult {
   name: string
   path: string
   files: string[]
+  assets: DesignPackageAssetInfo[]
   base?: string
   overwritten: boolean
 }
@@ -86,9 +90,52 @@ export interface ValidateDesignPackageResult {
   sections: string[]
   layouts: string[]
   components: string[]
+  assets: DesignPackageAssetInfo[]
   errors: string[]
 }
 
+export interface DesignPackageAssetInput {
+  path: string
+  content?: string
+  contentBase64?: string
+  sourcePath?: string
+}
+
+export interface DesignPackageAssetInfo {
+  path: string
+  kind: "cover-background" | "closing-background" | "background" | "logo" | "asset"
+  mimeType: string
+  bytes: number
+}
+
+export interface PackDesignPackageArgs {
+  workspaceRoot?: string
+  name: string
+  source?: "draft" | "installed"
+  outputPath?: string
+  format?: "tar.gz" | "tar"
+  overwrite?: boolean
+}
+
+export interface PackDesignPackageResult {
+  ok: true
+  name: string
+  archivePath: string
+  format: "tar.gz" | "tar"
+  files: string[]
+  assets: DesignPackageAssetInfo[]
+}
+
+export interface InstallDesignArchiveArgs {
+  archivePath: string
+  name?: string
+  overwrite?: boolean
+}
+
+export interface InstallDesignArchiveResult extends CreateDesignPackageResult {
+  archivePath: string
+}
+
 export interface DesignPreviewInfo {
   name: string
   designDir: string
@@ -283,6 +330,7 @@ export function createDesignPackage(args: CreateDesignPackageArgs): CreateDesign
   mkdirSync(target, { recursive: true })
   writeFileSync(join(target, "DESIGN.md"), `${designMd}\n`, "utf-8")
   writeFileSync(join(target, "preview.html"), `${previewHtml}\n`, "utf-8")
+  writeDesignAssets(target, args.assets)
 
   const validation = validateDesignPackage(name)
   if (!validation.ok) {
@@ -293,7 +341,8 @@ export function createDesignPackage(args: CreateDesignPackageArgs): CreateDesign
     ok: true,
     name,
     path: target,
-    files: ["DESIGN.md", "preview.html"],
+    files: listDesignPackageFiles(target),
+    assets: listDesignAssetsInDir(target),
     base: args.base,
     overwritten: existed,
   }
@@ -321,6 +370,7 @@ export function createDesignDraftPackage(args: CreateDesignDraftArgs): CreateDes
   mkdirSync(target, { recursive: true })
   writeFileSync(join(target, "DESIGN.md"), `${designMd}\n`, "utf-8")
   writeFileSync(join(target, "preview.html"), `${previewHtml}\n`, "utf-8")
+  writeDesignAssets(target, args.assets)
 
   const validation = validateDesignDraftPackage(args.workspaceRoot, name)
   if (!validation.ok) {
@@ -331,7 +381,8 @@ export function createDesignDraftPackage(args: CreateDesignDraftArgs): CreateDes
     ok: true,
     name,
     path: target,
-    files: ["DESIGN.md", "preview.html"],
+    files: listDesignPackageFiles(target),
+    assets: listDesignAssetsInDir(target),
     base: args.base,
     overwritten: existed,
   }
@@ -378,11 +429,74 @@ export function installDesignDraftPackage(args: InstallDesignDraftArgs): Install
     name,
     path: target,
     sourcePath,
-    files: ["DESIGN.md", "preview.html"],
+    files: listDesignPackageFiles(target),
+    assets: listDesignAssetsInDir(target),
     overwritten: existed,
   }
 }
 
+/** Package an installed design or workspace draft as a shareable .tar or .tar.gz archive. */
+export function packDesignPackage(args: PackDesignPackageArgs): PackDesignPackageResult {
+  const name = normalizeDesignName(args.name)
+  const source = args.source ?? (args.workspaceRoot && designDraftExists(args.workspaceRoot, name) ? "draft" : "installed")
+  const sourceDir = source === "draft" ? designDraftDir(args.workspaceRoot || process.cwd(), name) : resolveDesignDir(name)
+  if (!sourceDir || !existsSync(sourceDir)) throw new Error(`Design ${source} '${name}' is not available`)
+  const validation = source === "draft" ? validateDesignDraftPackage(args.workspaceRoot || process.cwd(), name) : validateDesignPackage(name)
+  if (!validation.ok) throw new Error(`Design ${source} is invalid: ${validation.errors.join("; ")}`)
+
+  const format = args.format ?? "tar.gz"
+  const archivePath = resolve(args.outputPath || join(args.workspaceRoot || process.cwd(), ".revela", "design-archives", `${name}.${format}`))
+  if (existsSync(archivePath) && !args.overwrite) throw new Error(`Archive already exists: ${archivePath}`)
+  const entries = collectDirectoryEntries(sourceDir, name)
+  writeTarArchive(entries, archivePath, format === "tar.gz")
+  return {
+    ok: true,
+    name,
+    archivePath,
+    format,
+    files: listDesignPackageFiles(sourceDir),
+    assets: listDesignAssetsInDir(sourceDir),
+  }
+}
+
+/** Install a .tar or .tar.gz design archive into the user-level design registry. */
+export function installDesignArchive(args: InstallDesignArchiveArgs): InstallDesignArchiveResult {
+  const archivePath = resolve(args.archivePath)
+  if (!existsSync(archivePath)) throw new Error(`Archive does not exist: ${archivePath}`)
+  if (!archivePath.endsWith(".tar") && !archivePath.endsWith(".tar.gz") && !archivePath.endsWith(".tgz")) {
+    throw new Error("Design archive must be .tar, .tar.gz, or .tgz")
+  }
+
+  const entries = normalizePackageArchiveEntries(readTarArchive(archivePath))
+  const tmp = join(tmpdir(), `revela-design-install-${Date.now()}`)
+  try {
+    extractEntriesToDirectory(entries, tmp)
+    const info = parseDesignFile(join(tmp, "DESIGN.md"))
+    const name = normalizeDesignName(args.name || info?.name || basename(archivePath).replace(/\.tar\.gz$|\.tgz$|\.tar$/i, ""))
+    const validation = validateDesignPackageAt(name, tmp)
+    if (!validation.ok) throw new Error(`Design archive is invalid: ${validation.errors.join("; ")}`)
+
+    const target = join(DESIGNS_DIR, name)
+    const existed = existsSync(target)
+    if (existed && !args.overwrite) throw new Error(`Design '${name}' already exists. Pass overwrite=true to replace it.`)
+
+    mkdirSync(DESIGNS_DIR, { recursive: true })
+    if (existed) rmSync(target, { recursive: true, force: true })
+    cpSync(tmp, target, { recursive: true })
+    return {
+      ok: true,
+      name,
+      path: target,
+      archivePath,
+      files: listDesignPackageFiles(target),
+      assets: listDesignAssetsInDir(target),
+      overwritten: existed,
+    }
+  } finally {
+    rmSync(tmp, { recursive: true, force: true })
+  }
+}
+
 function hasDataAttribute(html: string, attr: string, value: string): boolean {
   const escaped = value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
   return new RegExp(`${attr}\\s*=\\s*(["'])${escaped}\\1`).test(html)
@@ -451,10 +565,12 @@ function validateDesignPackageAt(nameInput: string, dir: string): ValidateDesign
   let sections: string[] = []
   let layouts: string[] = []
   let components: string[] = []
+  let assets: DesignPackageAssetInfo[] = []
 
   if (!existsSync(dir)) errors.push(`Design directory does not exist: ${dir}`)
   if (!hasDesignMd) errors.push("DESIGN.md is missing")
   if (!hasPreview) errors.push("preview.html is missing")
+  if (existsSync(dir)) assets = listDesignAssetsInDir(dir)
 
   if (hasDesignMd) {
     const info = parseDesignFile(mdPath)
@@ -501,6 +617,7 @@ function validateDesignPackageAt(nameInput: string, dir: string): ValidateDesign
     sections,
     layouts,
     components,
+    assets,
     errors,
   }
 }
@@ -509,6 +626,107 @@ function designDraftDir(workspaceRoot: string, name: string): string {
   return resolve(workspaceRoot, ".revela", "drafts", "designs", name)
 }
 
+function designDraftExists(workspaceRoot: string, name: string): boolean {
+  const dir = designDraftDir(workspaceRoot, name)
+  return existsSync(dir) && statSync(dir).isDirectory() && existsSync(join(dir, "DESIGN.md"))
+}
+
+function writeDesignAssets(targetDir: string, assets?: DesignPackageAssetInput[]): void {
+  if (!assets || assets.length === 0) return
+  for (const asset of assets) {
+    const rel = normalizeAssetPath(asset.path)
+    const target = resolve(targetDir, rel)
+    if (target !== resolve(targetDir) && !target.startsWith(resolve(targetDir) + sep)) {
+      throw new Error(`Asset path escapes design package: ${asset.path}`)
+    }
+    let bytes: Buffer
+    if (asset.contentBase64 !== undefined) bytes = Buffer.from(asset.contentBase64, "base64")
+    else if (asset.content !== undefined) bytes = Buffer.from(asset.content, "utf-8")
+    else if (asset.sourcePath !== undefined) {
+      const source = resolve(asset.sourcePath)
+      if (!existsSync(source) || !statSync(source).isFile()) throw new Error(`Asset source file does not exist: ${asset.sourcePath}`)
+      bytes = readFileSync(source)
+    } else {
+      throw new Error(`Asset '${asset.path}' requires content, contentBase64, or sourcePath`)
+    }
+    mkdirSync(dirname(target), { recursive: true })
+    writeFileSync(target, bytes as any)
+  }
+}
+
+function normalizeAssetPath(pathInput: string): string {
+  const normalized = pathInput.replace(/\\/g, "/").replace(/^\.\/+/, "")
+  if (!normalized.startsWith("assets/")) throw new Error(`Design asset path must be located under assets/: ${pathInput}`)
+  if (normalized.includes("\0") || normalized.startsWith("/") || normalized.split("/").some((part) => !part || part === "." || part === "..")) {
+    throw new Error(`Design asset path must be located under assets/ and must not contain absolute paths, empty segments, '.', '..', or NUL characters: ${pathInput}`)
+  }
+  return normalized
+}
+
+function listDesignPackageFiles(dir: string): string[] {
+  if (!existsSync(dir)) return []
+  const root = resolve(dir)
+  const files: string[] = []
+  walk(root)
+  return files.sort()
+
+  function walk(current: string): void {
+    for (const entry of readdirSync(current).sort()) {
+      if (entry === ".DS_Store" || entry.startsWith(".")) continue
+      const abs = join(current, entry)
+      const stat = lstatSync(abs)
+      if (stat.isSymbolicLink()) continue
+      if (stat.isDirectory()) {
+        walk(abs)
+        continue
+      }
+      if (!stat.isFile()) continue
+      files.push(relative(root, abs).split(sep).join("/"))
+    }
+  }
+}
+
+function listDesignAssetsInDir(dir: string): DesignPackageAssetInfo[] {
+  const files = listDesignPackageFiles(dir).filter((file) => file.startsWith("assets/"))
+  return files.map((file) => {
+    const abs = join(dir, ...file.split("/"))
+    return {
+      path: file,
+      kind: inferAssetKind(file),
+      mimeType: mimeTypeForDesignAsset(file),
+      bytes: statSync(abs).size,
+    }
+  })
+}
+
+export function listDesignAssets(nameInput?: string): DesignPackageAssetInfo[] {
+  const name = normalizeDesignName(nameInput || activeDesign())
+  const designDir = resolveDesignDir(name)
+  if (!designDir) throw new Error(`Design '${name}' is not installed`)
+  return listDesignAssetsInDir(designDir)
+}
+
+function inferAssetKind(path: string): DesignPackageAssetInfo["kind"] {
+  const lower = path.toLowerCase()
+  if (lower.includes("cover") && lower.includes("background")) return "cover-background"
+  if ((lower.includes("closing") || lower.includes("close")) && lower.includes("background")) return "closing-background"
+  if (lower.includes("background") || lower.includes("/bg-") || lower.includes("-bg.")) return "background"
+  if (lower.includes("logo")) return "logo"
+  return "asset"
+}
+
+function mimeTypeForDesignAsset(path: string): string {
+  const lower = path.toLowerCase()
+  if (lower.endsWith(".png")) return "image/png"
+  if (lower.endsWith(".jpg") || lower.endsWith(".jpeg")) return "image/jpeg"
+  if (lower.endsWith(".webp")) return "image/webp"
+  if (lower.endsWith(".gif")) return "image/gif"
+  if (lower.endsWith(".svg")) return "image/svg+xml"
+  if (lower.endsWith(".css")) return "text/css"
+  if (lower.endsWith(".json")) return "application/json"
+  return "application/octet-stream"
+}
+
 // ---------------------------------------------------------------------------
 // Marker-based section / component parsing
 // ---------------------------------------------------------------------------
@@ -553,6 +771,7 @@ export interface DesignInventory {
   sections: string[]
   layouts: DesignInventoryLayout[]
   components: DesignInventoryComponent[]
+  assets: DesignPackageAssetInfo[]
   hasMarkers: boolean
 }
 
@@ -690,6 +909,7 @@ export function getDesignInventory(designName?: string): DesignInventory {
       description: designBlockDescription(content),
       nesting: inferComponentNesting(componentName),
     })),
+    assets: listDesignAssetsInDir(designDir),
     hasMarkers,
   }
 }

package/lib/runtime/index.ts

@@ -11,11 +11,15 @@ import {
   getDesignLayout,
   getDesignSection,
   getDesignSkillMd,
+  installDesignArchive,
   installDesignDraftPackage,
+  listDesignAssets,
   listDesigns,
+  packDesignPackage,
   seedBuiltinDesigns,
   validateDesignDraftPackage,
   validateDesignPackage,
+  type DesignPackageAssetInput,
 } from "../design/designs"
 import { createDeckFoundation as createDeckFoundationShell } from "../deck-html/foundation"
 import { activeDomain, activateDomain, createDomainDraftPackage, createDomainPackage, getDomainSkillMd, installDomainDraftPackage, listDomains, seedBuiltinDomains, validateDomainDraftPackage, validateDomainPackage } from "../domain/domains"
@@ -85,6 +89,7 @@ export interface RuntimeDesignCreateInput {
   base?: string
   designMd: string
   previewHtml: string
+  assets?: DesignPackageAssetInput[]
   overwrite?: boolean
 }
 
@@ -103,6 +108,21 @@ export interface RuntimeDraftInstallInput extends RuntimeWorkspaceInput {
   overwrite?: boolean
 }
 
+export interface RuntimeDesignPackInput extends RuntimeWorkspaceInput {
+  name: string
+  source?: "draft" | "installed"
+  outputPath?: string
+  format?: "tar.gz" | "tar"
+  overwrite?: boolean
+}
+
+export interface RuntimeDesignArchiveInstallInput {
+  archivePath: string
+  name?: string
+  overwrite?: boolean
+  activate?: boolean
+}
+
 export interface RuntimeNameInput {
   name: string
 }
@@ -296,6 +316,7 @@ export function designRead(input: RuntimeDesignReadInput = {}) {
       name,
       section: input.section,
       markdown,
+      assets: listDesignAssets(name),
     }
     if (input.section === "rules") recordDesignRulesRead(root(input.workspaceRoot), name, markdown)
     return result
@@ -304,6 +325,7 @@ export function designRead(input: RuntimeDesignReadInput = {}) {
     ok: true,
     name,
     markdown: getDesignSkillMd(name),
+    assets: listDesignAssets(name),
   }
 }
 
@@ -341,6 +363,7 @@ export function designCreate(input: RuntimeDesignCreateInput) {
     base: input.base,
     designMd: requiredString(input?.designMd, "designMd"),
     previewHtml: requiredString(input?.previewHtml, "previewHtml"),
+    assets: input.assets,
     overwrite: input.overwrite ?? false,
   })
 }
@@ -356,6 +379,7 @@ export function designDraftCreate(input: RuntimeDesignDraftCreateInput) {
     base: input.base,
     designMd: requiredString(input?.designMd, "designMd"),
     previewHtml: requiredString(input?.previewHtml, "previewHtml"),
+    assets: input.assets,
     overwrite: input.overwrite ?? false,
   })
 }
@@ -373,6 +397,31 @@ export function designDraftInstall(input: RuntimeDraftInstallInput) {
   })
 }
 
+export function designPack(input: RuntimeDesignPackInput) {
+  return packDesignPackage({
+    workspaceRoot: root(input.workspaceRoot),
+    name: requiredName(input, "design"),
+    source: input.source,
+    outputPath: input.outputPath,
+    format: input.format,
+    overwrite: input.overwrite ?? false,
+  })
+}
+
+export function designInstallArchive(input: RuntimeDesignArchiveInstallInput) {
+  seedBuiltinDesigns()
+  const installed = installDesignArchive({
+    archivePath: requiredString(input?.archivePath, "archivePath"),
+    name: input.name,
+    overwrite: input.overwrite ?? false,
+  })
+  if (input.activate) {
+    activateDesign(installed.name)
+    return { ...installed, activated: true, activeDesign: installed.name }
+  }
+  return { ...installed, activated: false }
+}
+
 export interface DesignRulesReadinessResult {
   ok: boolean
   activeDesign: string

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyber-dash-tech/revela",
-  "version": "0.18.9",
+  "version": "0.18.11",
   "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.18.9", "mcp"]
+      "args": ["-y", "@cyber-dash-tech/revela@0.18.11", "mcp"]
     }
   }
 }

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

@@ -28,6 +28,8 @@ type RuntimeModule = {
   designDraftCreate(input: any): any
   designDraftValidate(input: any): any
   designDraftInstall(input: any): any
+  designPack(input: any): any
+  designInstallArchive(input: any): any
   domainList(): any
   domainRead(input?: any): any
   domainActivate(input: any): any
@@ -175,6 +177,7 @@ const tools = [
       base: stringProp("Optional base design used as structural scaffold."),
       designMd: requiredStringProp("Complete DESIGN.md content."),
       previewHtml: requiredStringProp("Complete preview.html content."),
+      assets: designAssetsProp(),
       overwrite: booleanProp("Whether to replace an existing local design package. Defaults to false."),
     }, ["name", "designMd", "previewHtml"]),
   },
@@ -192,6 +195,7 @@ const tools = [
       base: stringProp("Optional base design used as structural scaffold."),
       designMd: requiredStringProp("Complete DESIGN.md content."),
       previewHtml: requiredStringProp("Complete preview.html content."),
+      assets: designAssetsProp(),
       overwrite: booleanProp("Whether to replace an existing workspace draft. Defaults to false."),
     }, ["name", "designMd", "previewHtml"]),
   },
@@ -212,6 +216,28 @@ const tools = [
       overwrite: booleanProp("Whether to replace an existing user-level design package. Defaults to false."),
     }, ["name"]),
   },
+  {
+    name: "revela_design_pack",
+    description: "Package an installed or workspace-draft Revela design as a shareable .tar or .tar.gz archive.",
+    inputSchema: objectSchema({
+      workspaceRoot: stringProp("Optional workspace root. Used for draft source lookup and default output path."),
+      name: requiredStringProp("Design name in kebab-case."),
+      source: enumProp(["draft", "installed"], "Package a workspace draft or installed design. Defaults to draft when a matching draft exists."),
+      outputPath: stringProp("Optional archive output path. Defaults to .revela/design-archives/{name}.tar.gz under the workspace."),
+      format: enumProp(["tar.gz", "tar"], "Archive format. Defaults to tar.gz."),
+      overwrite: booleanProp("Whether to replace an existing archive. Defaults to false."),
+    }, ["name"]),
+  },
+  {
+    name: "revela_design_install_archive",
+    description: "Install a local .tar or .tar.gz Revela design archive into the user-level design registry.",
+    inputSchema: objectSchema({
+      archivePath: requiredStringProp("Local path to a .tar, .tar.gz, or .tgz design archive."),
+      name: stringProp("Optional installed design name override."),
+      overwrite: booleanProp("Whether to replace an existing user-level design package. Defaults to false."),
+      activate: booleanProp("Whether to activate the design after installation. Defaults to false."),
+    }, ["archivePath"]),
+  },
   {
     name: "revela_domain_list",
     description: "List installed Revela narrative domains and the active domain.",
@@ -410,6 +436,8 @@ async function callTool(name: string, args: any): Promise<any> {
   if (name === "revela_design_draft_create") return r.designDraftCreate(args)
   if (name === "revela_design_draft_validate") return r.designDraftValidate(args)
   if (name === "revela_design_draft_install") return r.designDraftInstall(args)
+  if (name === "revela_design_pack") return r.designPack(args)
+  if (name === "revela_design_install_archive") return r.designInstallArchive(args)
   if (name === "revela_domain_list") return r.domainList()
   if (name === "revela_domain_read") return r.domainRead(args)
   if (name === "revela_domain_activate") return r.domainActivate(args)
@@ -495,6 +523,24 @@ function arrayObjectProp(description: string) {
   }
 }
 
+function designAssetsProp() {
+  return {
+    type: "array",
+    description: "Optional design-owned assets for user-uploaded or local materials to archive under assets/**. Each item must use path plus content, contentBase64, or sourcePath.",
+    items: {
+      type: "object",
+      properties: {
+        path: { type: "string", description: "Package-relative asset path for uploaded or local design material. Must start with assets/." },
+        content: { type: "string", description: "UTF-8 text asset content." },
+        contentBase64: { type: "string", description: "Base64-encoded binary asset content." },
+        sourcePath: { type: "string", description: "Local file path to copy into the design asset." },
+      },
+      required: ["path"],
+      additionalProperties: false,
+    },
+  }
+}
+
 function componentPlanArrayProp() {
   const childSchema: any = {
     type: "object",

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

@@ -1,17 +1,21 @@
 ---
 name: revela-design
-description: Create, edit, validate, install, activate, inspect, or list Revela design packages in Codex using design MCP tools.
+description: Create, edit, validate, package, share, install, activate, inspect, or list Revela design packages in Codex using design MCP tools.
 ---
 
 # Revela Design
 
-Use this skill when the user asks to create, customize, edit, validate, install, activate, inspect, list, or switch a Revela design.
+Use this skill when the user asks to create, customize, edit, validate, package, share, install, activate, inspect, list, or switch a Revela design.
 
 ## Contract
 
 - Designs define deck visual systems: rules, foundation, layouts, components, chart rules, and preview coverage.
+- Designs may include package-owned `assets/**` such as cover or closing backgrounds; design tools surface these as design elements, not source evidence.
+- When the user uploads or provides logo, cover, closing, background, texture, brand image, or similar design material, store it inside the design package with `revela_design_draft_create.assets`; use paths under `assets/**` only.
+- Generated `preview.html` must actually reference uploaded design assets with package-relative `assets/...` paths rather than describing them only in text.
 - Default authoring is workspace draft first, then validate, then install only when appropriate.
 - Direct user-level creation is reserved for explicit create/install-now requests.
+- Shareable design archives are `.tar` or `.tar.gz`; install archives only from trusted local paths.
 - Do not use domain tools for visual design work.
 - Do not generate deck HTML while authoring a design.
 
@@ -28,12 +32,20 @@ For new or edited designs:
 1. Call `revela_design_list`.
 2. Read the requested base design or active design with `revela_design_read`.
 3. Draft complete `DESIGN.md` and complete `preview.html` content.
-4. Call `revela_design_draft_create`.
+4. Call `revela_design_draft_create`; when uploaded or local design material exists, pass `assets: [{ path: "assets/...", contentBase64|content|sourcePath }]` so the files are written into the draft package.
 5. Call `revela_design_draft_validate`.
 6. If validation fails, revise the draft content and repeat draft create/validate.
 7. Call `revela_design_draft_install` only after the draft validates and the user intent is to install it.
 8. Call `revela_design_activate` only when the user asks to make it active.
 
+For sharing or installing design archives:
+
+1. Call `revela_design_draft_validate` or `revela_design_validate` before packaging.
+2. Call `revela_design_pack` to create a `.tar.gz` archive from a workspace draft or installed design.
+3. Call `revela_design_install_archive` to install a local `.tar` or `.tar.gz` archive.
+4. After archive installation, call `revela_design_inventory` or `revela_design_read` to confirm the design and assets are readable.
+5. Call `revela_design_activate` only when the user asks to make the installed design active, or use `activate: true` on archive install when the request is explicit.
+
 Use `revela_design_create` only when the user explicitly requests direct local creation outside the workspace draft workflow. Follow it with `revela_design_validate`.
 
 ## Design Package Requirements
@@ -41,13 +53,19 @@ Use `revela_design_create` only when the user explicitly requests direct local c
 - Use a kebab-case design name.
 - `DESIGN.md` must include valid frontmatter and complete design marker sections.
 - Include design rules, foundation guidance, at least one layout, and at least one component.
+- Optional assets must live under `assets/**`; reference them as package-relative paths like `assets/cover-background.png`.
+- `DESIGN.md` may reference package assets in rules, layouts, or components with `assets/...`; do not reference workspace `assets/` media manifest entries for design-owned visuals.
 - `preview.html` must use the fixed Revela preview canvas contract and visibly preview the design.
+- If design assets are present, `preview.html` must visibly use the saved `assets/...` files, for example a cover hero background or logo image.
 - Preview must include cover and closing examples and showcase every component.
 - Preserve source inspiration and limitations explicitly; do not copy copyrighted design text or assets into the package.
 
 ## Outputs
 
 - Design draft path/status or installed design name.
+- Archive path/status when packaging or installing a shareable design.
+- Asset metadata surfaced by read/inventory tools when `assets/**` exists.
+- Saved asset paths and intended uses, for example `assets/cover-background.png -> cover hero background`.
 - Validation result and any remaining diagnostics.
 - Whether the design was activated.
 - Next step, usually `revela-research` for planning with the design or `revela-make-deck` when a valid `deck-plan.md` already exists.

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

@@ -48,12 +48,21 @@ Use this skill to turn user intent and available workspace context into a concis
 - `## Audience`
 - `## Decision Or Action`
 - `## Output`
+- `## Language`
+- `## Domain / Use Case`
+- `## Design`
 - `## Constraints`
 - `## Available Materials`
 - `## Known Gaps`
 - `## Acceptance Criteria`
 - `## Recommended Next Step`
 
+Section expectations:
+
+- `## Language`: output language, terminology preference, and localization notes.
+- `## Domain / Use Case`: active or requested domain, business/use-case context, and decision context.
+- `## Design`: active or requested design, visual direction, and brand/style constraints.
+
 Use explicit `Unknown` or `Pending user input` entries instead of inventing requirements.
 
 ## Outputs