coolcanvas 0.0.0-stage → 1.0.0-beta.1

package/README.md

@@ -1,3 +1,42 @@
-# Temporary Holding Version
+# Cool Canvas 命令行安装
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+测试版通过 npm 的 beta 标签发布：`npm install --global coolcanvas@beta`。项目源码保留 private:true，只有白名单构建产物可发布。
+
+需要 Node.js 22.19.0 或更高兼容版本及 npm。FFmpeg/ffprobe、Codex CLI、即梦 CLI、视频解析所需 Chromium 等按所用功能准备；本包不封装这些外部环境，不包含任何人的登录授权。AI 服务仍需用户自己的账号或密钥。
+
+发布后的安装入口为 `npm install --global coolcanvas`。macOS 在全局目录需要管理员权限时可用 `sudo npm install --global coolcanvas`；Windows 不使用 sudo。启动、停止和更新始终以普通用户身份运行。
+
+```sh
+coolcanvas start
+coolcanvas status
+coolcanvas restart
+coolcanvas stop
+```
+
+`start` 在后台启动本地服务，确认启动成功后打开默认浏览器。重复启动复用同一实例；`restart` 在未运行时启动。端口被其他进程占用时明确报错，不终止其他进程。默认访问 http://127.0.0.1:4780 。
+
+首次启动会自动准备运行目录并验证实际读写能力；macOS/Linux将当前用户拥有的运行目录设为700、运行记录与数据库等私有文件设为600，并使用077 umask创建后续文件。Windows沿用用户目录的系统ACL，执行真实写入/重命名/删除检查，不把chmod当作ACL授权。不会在sudo安装阶段创建用户数据，也不会对全局安装目录或其他账号的数据执行chmod/chown。已有异常权限能在当前用户权限内修复时自动修复；只读磁盘、其他账号拥有的旧目录或系统安全限制会明确报错并保留原数据，不换到空目录。
+
+用户数据存放在 `~/.coolcanvas/data`，更新包存放在 `~/.coolcanvas/releases`。不会读取开发项目的 data 或 .env，也不会自动迁移旧工作区。可用 `COOLCANVAS_HOME` 指定独立目录、`COOLCANVAS_PORT` 指定端口、`COOLCANVAS_NO_OPEN=1` 禁止自动打开浏览器。
+
+页面定期查询 npm：beta 版本监听 coolcanvas/beta，正式版本监听 coolcanvas/latest；只有经过包标识验证的较新版本才提示。用户点击更新后，先保存画布，下载到用户目录，校验安装结果，在没有生成、对话或保存任务时重启；启动失败恢复旧代码，保留旧包和用户数据。更新不会 sudo、不会覆盖全局安装目录。存在未处理草稿、冲突或打开的弹窗时不刷新。
+
+首页右上角「添加桌面图标」会在当前账号桌面创建带鱼形Logo的启动入口：macOS为Cool Canvas.app，Windows为Cool Canvas.lnk（通过系统获取实际桌面目录，兼容重定向桌面）。双击调用安装版CLI的start，保留创建时使用的数据目录与端口，不依赖终端PATH寻找Node/CLI。已有本实例入口重复点击不新增；同名其他文件拒绝覆盖。系统限制桌面访问时需要用户允许访问后重试。开发服务器按钮会提示使用coolcanvas start启动，不伪造创建成功。
+
+全局命令作为启动入口，每次启动选择用户目录中已成功安装的版本；以后用 npm 手动全局升级到更高版本也会优先使用更高版本。`coolcanvas --version` 显示全局入口版本，`coolcanvas status` 显示实际运行版本。
+
+## 本地验证
+
+```sh
+npm ci
+npm run package:local
+# 将路径替换为实际生成的 tgz；使用隔离 prefix 不改动现有全局工具。
+npm install --global --prefix /tmp/coolcanvas-local ./output/npm/coolcanvas-1.0.0-beta.0.tgz
+COOLCANVAS_HOME=/tmp/coolcanvas-local-data COOLCANVAS_PORT=14780 /tmp/coolcanvas-local/bin/coolcanvas start
+```
+
+Windows 的隔离 prefix 下命令入口为 `coolcanvas.cmd`，环境变量使用 PowerShell 的 `$env:COOLCANVAS_HOME` 等设置。仅 macOS 本机实际验证，Windows 需要 Windows 机器进一步验证。
+
+生成包只包含生产网页、后端/CLI 构建代码、公开模板目录和运行依赖声明。不会打包 `.env`、`data/`、认证目录、测试截图或 Git。模板媒体目前位于开发数据目录，未纳入安装包，因此这些内置模板视频尚不能在新安装中播放；不以复制整个 data 解决。
+
+本地更新测试可在 `COOLCANVAS_TEST_MODE=1` 时设置 `COOLCANVAS_TEST_REGISTRY=http://127.0.0.1:端口`，仅允许回环 HTTP mock registry。正常运行固定使用 HTTPS npm 官方 registry，保留 TLS 校验。不要向测试 registry 提供真实凭据。