@cyber-dash-tech/revela 0.18.8 → 0.18.10

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-722%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-726%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.8 mcp` to start the MCP server.
+- Your environment must be able to run `npx`; Revela uses `npx -y @cyber-dash-tech/revela@0.18.10 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.8
+codex plugin marketplace add https://github.com/cyber-dash-tech/revela --ref v0.18.10
 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.8 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.10 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-722%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-726%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.8 mcp` 启动 MCP server。
+- 环境中需要可以执行 `npx`；Revela 会用 `npx -y @cyber-dash-tech/revela@0.18.10 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.8
+codex plugin marketplace add https://github.com/cyber-dash-tech/revela --ref v0.18.10
 codex plugin add revela@revela
 ```
 
-Git marketplace 安装的是 Codex plugin 壳、skills、hooks 和 MCP 配置。Codex 第一次启动 Revela MCP server 时，会运行 `npx -y @cyber-dash-tech/revela@0.18.8 mcp`，由 npm 获取已发布 package 及其 dependencies。
+Git marketplace 安装的是 Codex plugin 壳、skills、hooks 和 MCP 配置。Codex 第一次启动 Revela MCP server 时，会运行 `npx -y @cyber-dash-tech/revela@0.18.10 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 paths must start with assets/: ${pathInput}`)
+  if (normalized.includes("\0") || normalized.startsWith("/") || normalized.split("/").some((part) => !part || part === "." || part === "..")) {
+    throw new Error(`Invalid design asset path: ${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,
   }
 }