feat(package): add portable .dreamskin import and export

[rwang23]

English

Summary

• Add a versioned, single-file .dreamskin Package v1 for one explicit Theme v1 descriptor, one primary PNG/JPEG/WebP image, and an optional preview.
• Expose the same dependency-free inspectPackage, exportPackage, and importPackage interface from byte-identical macOS and Windows modules, plus matching CLI commands.
• Keep import save-only: it validates and publishes a new theme directory, but never activates a theme, restarts Codex, touches the official installation, or contacts the network.
• Add a Draft 2020-12 JSON Schema, complete English and Chinese documentation, changelog entries, standalone macOS archive integration, and cross-platform regression coverage.

Closes #108.

This complements the Theme v1 work from #63 / #101. Packages require an explicit schemaVersion: 1, while this PR deliberately leaves the platform theme loaders, injector, renderer, CSS, and active-theme switching paths unchanged.

Design and safety details

• Package v1 is a bounded UTF-8 JSON envelope rather than ZIP. It needs no archive dependency and has one canonical representation for deterministic exports.
• Limits are enforced before publication: 30 MiB outer package, 20 MiB total decoded content, 1 MiB theme JSON, 16 MiB / 16,384 px / 50 MP primary image, and 3 MiB / 4,096 px / 16 MP preview.
• Parsing rejects BOMs, malformed UTF-8, duplicate keys, trailing data, excessive nesting, unsupported fields, non-canonical base64, byte-length mismatches, and SHA-256 mismatches.
• Image paths are NFC basenames and reject separators, control characters, trailing dots/spaces, Windows device names, unsafe Windows characters, and portable case-folding collisions.
• Extension, media type, image magic bytes, and dimensions must agree. theme.image must exactly match the packaged image path.
• Export uses an exclusive sibling temporary file, fsync/readback/full validation, and an exclusive same-directory hard link. It never replaces an existing output.
• Import validates first, stages privately, reads back, creates a new destination exclusively, publishes the image first, and publishes theme.json last as the commit marker. It never replaces an existing theme.
• Cleanup removes only task-created files/directories whose filesystem identity still matches, including the post-publication readback failure path.
• SHA-256 is documented as integrity/content identity, not an author signature. The optional preview is validated but never installed into the runtime theme directory.

Conflict minimization

• The implementation, tests, schema, and package guide are new files.
• The feat(windows): add split-image Theme Studio #96 overlap is limited to windows/CHANGELOG.md; our entry is at the end of the existing 新增 block, while feat(windows): add split-image Theme Studio #96 adds a separate Unreleased section.
• The feat(theme): define a versioned portable contract #101 overlap is limited to the two changelogs and macos/tests/run-tests.sh; our edits use separate hunks from its Theme v1 runner hook.
• Git three-way merge-tree checks completed successfully against the current heads of both feat(windows): add split-image Theme Studio #96 (0aed829) and feat(theme): define a versioned portable contract #101 (6ecad13).

Type

• Bug fix
• Feature
• Docs
• Theme / CSS / visual
• Scripts / install / restore
• Chore

Platform

• macOS
• Windows
• Both
• Docs / repo only

Self-check

Docs-only

• Links and wording reviewed

macOS

• macos/tests/run-tests.sh passed
• Doctor (optional): macos/scripts/doctor-macos.sh
• Live verify (if inject/CSS/start path): verify-dream-skin-macos.sh or Desktop Verify
• Restore / re-apply smoke (if install/restore/start changed)

Windows

• Relevant install / start / verify / restore scripts exercised
• Environment noted below (OS build, Codex source)

User-facing

• Updated macos/CHANGELOG.md and windows/CHANGELOG.md; no version bump
• N/A — no user-facing change

Security

• Does not modify the official Codex install, app.asar, or signatures
• Does not silently write API Base URL or keys
• CDP remains loopback-oriented where applicable; no CDP code changes

Notes and verification

• Real bundled-theme round trip: exported macos/presets/preset-midnight-aurora with the macOS entry point, inspected/imported/re-exported it with the Windows entry point, then inspected the second package with the macOS entry point. Both package SHA-256 values were 9ef31e2571e4d58f6f05c2237e3dd2fc3fc4159d0771007babae40085a313697; theme and image bytes were exact; content ID was bc867af5ca1104e4495fc9cfd9d15b9adc267ecaa97ec2fbc6844f67ec49e5f8.
• Windows Node v24.15.0 package tests: 20 passed, 4 platform-specific skips across the two byte-identical suites.
• Linux Node 22 portable regressions: macOS 16 passed; Windows 15 passed with one intentional skip for the Windows copy of the macOS standalone-archive assertion.
• Windows regression suite passed under Windows PowerShell 5.1 and PowerShell 7.
• Shell syntax, Node syntax, both injector payload checks, runtime-safety assertions, version consistency, git diff --check, UTF-8/BOM/trailing-whitespace checks, platform byte parity, and changed local documentation links passed.
• Draft 2020-12 schema validation passed for the schema itself and a representative package.
• macos/tests/run-tests.sh was also run in the Linux container. It passed the preliminary Node regressions and the standalone-archive checks, then reached the existing macOS-only theme-switch fixture, where GNU /usr/bin/stat does not support the BSD -f %z form. The checkbox remains unchecked; the package workflow is covered by the portable suites and the full round trip above.
• Environment: Windows 11 Home 10.0.26200 (build 26200), x64; Node v24.15.0; Windows PowerShell 5.1.26100.8875; PowerShell 7.6.3; Microsoft Store OpenAI.Codex 26.715.2305.0.
• No screenshots are included because this change adds a data/CLI interface and does not change visual rendering.

---

中文

摘要

• 新增带版本的 .dreamskin Package v1 单文件格式：一个包包含一份显式 Theme v1 描述、一张 PNG/JPEG/WebP 主图片，以及一张可选预览图。
• macOS 与 Windows 提供字节完全一致、零第三方依赖的 inspectPackage、exportPackage、importPackage 模块接口和对应 CLI 命令。
• 导入只负责保存：完成校验并发布一个全新的主题目录，但不会自动激活主题、重启 Codex、修改官方安装，也不会访问网络。
• 同时补充 Draft 2020-12 JSON Schema、完整中英文文档、两端 changelog、macOS 独立发行包文档集成，以及跨平台回归测试。

Closes #108。

该功能与 #63 / #101 的 Theme v1 工作配套。Package 要求主题显式声明 schemaVersion: 1；本 PR 不改平台主题加载器、injector、renderer、CSS 或当前主题切换流程。

设计与安全细节

• Package v1 使用有明确上限的 UTF-8 JSON envelope，不采用 ZIP，因此无需新增压缩依赖，也能为确定性导出保留唯一规范表示。
• 发布前会执行固定限制：外层包 30 MiB、全部解码内容 20 MiB、主题 JSON 1 MiB、主图片 16 MiB / 单边 16,384 px / 50 MP、预览图 3 MiB / 单边 4,096 px / 16 MP。
• 解析会拒绝 BOM、非法 UTF-8、重复键、尾随数据、过深嵌套、未支持字段、非规范 base64、字节数不符与 SHA-256 不符。
• 图片路径只能使用 NFC basename；拒绝路径分隔符、控制字符、尾随空格或点、Windows 保留设备名、Windows 不安全字符，以及大小写折叠后的路径冲突。
• 扩展名、媒体类型、图片 magic bytes 与尺寸必须一致，theme.image 也必须与包内图片路径完全一致。
• 导出先写同目录排他临时文件，执行 fsync、回读和完整校验，再通过同目录排他硬链接发布；已有输出永远不会被替换。
• 导入先完成校验，再写入私有 staging 目录并回读，然后排他创建新目标目录；先发布图片，最后发布作为 commit marker 的 theme.json，不会替换已有主题。
• 失败清理只处理本次任务创建且文件系统身份仍匹配的文件或目录，包括发布后回读失败这一条路径。
• 文档明确说明 SHA-256 只表示完整性和内容身份，不是作者签名；可选预览图会被完整校验，但不会安装到运行时主题目录。

冲突控制

• 核心实现、测试、Schema 和 Package 指南都是新文件。
• 与 feat(windows): add split-image Theme Studio #96 的重叠只剩 windows/CHANGELOG.md；本 PR 把条目放在当前“新增”段末尾，而 feat(windows): add split-image Theme Studio #96 新建独立的 Unreleased 段。
• 与 feat(theme): define a versioned portable contract #101 的重叠只剩两份 changelog 和 macos/tests/run-tests.sh；本 PR 的独立发行文档夹具与 Theme v1 runner hook 位于不同 hunk。
• 已针对 feat(windows): add split-image Theme Studio #96 当前头提交 0aed829 和 feat(theme): define a versioned portable contract #101 当前头提交 6ecad13 分别运行 Git 三方 merge-tree 检查，两次都成功且没有冲突。

类型

• 缺陷修复
• 新功能
• 文档
• 主题 / CSS / 视觉
• 脚本 / 安装 / 恢复
• 杂项

平台

• macOS
• Windows
• 双平台
• 仅文档或仓库元数据

自测

仅文档

• 已检查链接与表述

macOS

• 已通过 macos/tests/run-tests.sh
• Doctor（可选）：macos/scripts/doctor-macos.sh
• 改动注入/CSS/启动路径时执行 Verify
• 改动安装/恢复/启动时执行恢复再应用

Windows

• 已执行相关 install / start / verify / restore 脚本
• 已在下方注明系统版本和 Codex 来源

用户可见变更

• 已更新 macos/CHANGELOG.md 与 windows/CHANGELOG.md；未提升版本号
• 不适用——没有用户可见变更

安全

• 不修改官方 Codex 安装、app.asar 或签名
• 不静默写入 API Base URL 或 Key
• 适用时 CDP 仍只面向本机回环；本 PR 没有修改 CDP 代码

补充与验证

• 使用仓库真实预设完成双平台往返：macOS 入口导出 macos/presets/preset-midnight-aurora，Windows 入口检查、导入并重新导出，最后再由 macOS 入口检查第二个包。两次 Package SHA-256 都是 9ef31e2571e4d58f6f05c2237e3dd2fc3fc4159d0771007babae40085a313697，主题与图片字节完全一致，content ID 为 bc867af5ca1104e4495fc9cfd9d15b9adc267ecaa97ec2fbc6844f67ec49e5f8。
• Windows Node v24.15.0 Package 测试：两份字节一致的测试共 20 项通过，4 项因平台条件按预期跳过。
• Linux Node 22 可移植回归：macOS 16 项全部通过；Windows 15 项通过，1 项按预期跳过，该项只验证 macOS 独立发行包。
• Windows 完整回归在 Windows PowerShell 5.1 与 PowerShell 7 下均通过。
• Shell 语法、Node 语法、两端 injector payload、运行时安全断言、版本一致性、git diff --check、UTF-8/BOM/尾随空白、平台字节一致性，以及本次文档本地链接检查全部通过。
• Draft 2020-12 Schema 自身校验和代表性 Package 校验均通过。
• 也在 Linux 容器中运行了 macos/tests/run-tests.sh：前置 Node 回归和独立发行包检查均通过；之后进入现有的 macOS 专属主题切换夹具时，GNU /usr/bin/stat 不支持 BSD 的 -f %z 参数。对应复选框保持未勾选；Package 流程已由可移植测试和上述完整往返覆盖。
• 环境：Windows 11 Home 10.0.26200（build 26200），x64；Node v24.15.0；Windows PowerShell 5.1.26100.8875；PowerShell 7.6.3；Microsoft Store OpenAI.Codex 26.715.2305.0。
• 本次增加的是数据/CLI 接口，不改变视觉渲染，因此没有截图。

[Fei-Away]

Thanks for this! This overlaps with #137's approach to the same .dreamskin package idea — closing both for now, may revisit with a unified design later (both also predate the #216 runtime unification). Appreciate the effort!

感谢！这个和 #137 是同一个 .dreamskin 包方向的两套实现，先都关闭（也都早于 #216 的 runtime 统一），以后如果重提会走统一设计。谢谢你的付出！