maoda-commander-tt 0.0.47 → 0.0.48

package/README.md

@@ -24,7 +24,8 @@ template-commander/
 │   ├── commands/
 │   │   ├── hello/                 # 示例命令组
 │   │   ├── pippit/                # pippit 命令组
-│   │   └── git/                   # 新增 git 命令组
+│   │   ├── git/                   # git 命令组
+│   │   └── deploy/                # 静态文件部署与目录查询
 │   └── bedrock/                   # 本地补充基础设施
 │       ├── config/                # 本地配置读写
 │       ├── pkg/                   # package.json 查找
@@ -135,6 +136,141 @@ pnpm pub
 
 参见 [npm Trusted Publishing 文档](https://docs.npmjs.com/trusted-publishers/)。
 
+## 静态文件部署
+
+`tt deploy` 通过 HTTPS API 将现成的文件或目录部署到 nginx 静态目录，不执行构建。
+命令面向 AI 调用：stdout 只输出一个最终 JSON，诊断信息写入 stderr；失败时退出码为 1。
+`tt --help` 可发现该命令，`tt deploy --help` 查看完整说明。
+
+```bash
+# 将 dist 的内容直接部署为 demo 项目
+tt deploy ./dist --name demo
+
+# 单文件默认保持文件名，也可以用 --name 指定目标文件名
+tt deploy ./report.pdf
+tt deploy ./report.pdf --name latest-report.pdf
+
+# 查看部署根下的直接子目录及访问链接
+tt deploy --list
+
+# 不可恢复地删除根下一级文件或整个项目目录
+tt deploy --delete report.pdf
+tt deploy --delete demo
+```
+
+**独立项目直接部署在 tt 根目录下，无需刻意嵌套。** 当前服务器目标为
+`/root/repos/tt`：`tt deploy ./dist --name demo` 将目录内容直接放入
+`/root/repos/tt/demo/`，对应 `https://www.imaoda.com/tt/demo/`，不会额外套一层 `dist/`。
+目标名称只能是根下一级的名称，不能传 `group/demo`；`__catalog` 是保留名称。
+省略 `--name` 时使用源文件或目录的名称。
+
+**HTML 的静态资源使用相对于 HTML 的路径**，例如 `./assets/app.js`、`./style.css`
+和 `./images/cover.png`。避免 `/assets/app.js` 这类从域名根目录开始的路径，否则
+浏览器会请求项目目录之外的位置。部署前先产出适合子路径访问的静态文件。
+
+每次部署完整替换同名目标，包括移除旧版本中存在、本次已删除的文件。命令先上传到
+临时位置，上传成功后再发布。空目录会在上传前报错；目录里的符号链接和敏感文件
+（如 `.git`、`.env`、私钥）会导致整次部署拒绝，请只提供准备公开的静态产物。
+点开头的路径不会通过 nginx 公开；如果目录里只有这类文件，也会因没有可验证的
+公开内容而拒绝部署。
+
+### 本机配置与接口鉴权
+
+在 `~/.config/maoda-commander-tt/maoda-commander-tt.json` 的已有配置中增加
+`staticDeploy` 字段，保留其他字段。将示例 token 替换为已配置到服务器的固定 token：
+
+```json
+{
+  "staticDeploy": {
+    "apiUrl": "https://www.imaoda.com/api/tt",
+    "token": "<你的固定部署 token>"
+  }
+}
+```
+
+`apiUrl` 指向部署 API，命令自动为请求添加 `Authorization: Bearer <token>`。
+固定 token 只保存在本机配置中，不打包到 npm，也不放进命令行参数、公开目录或
+返回结果。部署不需要本机 SSH 权限；换电脑时配置同一 API 地址及 token 即可。
+本机需要 Node.js 22.13.0 或更高版本和 `tar`。API 只接受 HTTPS（本机测试的
+loopback HTTP 除外），客户端不跟随重定向，以免将 token 发送到其他地址。
+
+服务器使用 `TT_DEPLOY_TOKEN` 验证部署、删除和目录查询请求；`TT_DEPLOY_ROOT` 和
+`TT_DEPLOY_BASE_URL` 决定落盘根目录和公开 URL，不由调用端任意指定。
+当前限制为每次归档 50 MiB、最多 2 个并发操作。收到 token 的人可以部署、覆盖或删除
+这个根目录下的项目；需要更换时同时更新服务器和本机配置。
+
+服务器需要预先配置 API 和 nginx 路由，参见 [部署运维说明](ops/static-deploy/README.md)。
+当前服务器在静态入口上
+保留既有跨域响应头、OPTIONS 预检及 HSTS，并设置 `Cache-Control: no-cache`：
+允许浏览器缓存，但再次使用前向服务器确认内容是否更新。
+
+### 目录页与 AI 返回值
+
+浏览器目录入口为 `https://www.imaoda.com/tt/__catalog/`，JSON 清单入口为
+`https://www.imaoda.com/tt/__catalog/index.json`。目录页只列 `/root/repos/tt`
+下的直接子目录及链接，不列其他仓库、根下单文件或子目录里的文件；`/tt/` 本身
+不开放目录浏览。入口采用固定名称，知道链接的人都能看，不提供身份认证。
+每次部署、删除和 `--list` 都会更新清单，AI 可直接使用 `tt deploy --list` 获取同一范围。
+
+有首页的目录部署成功后，返回示例：
+
+```json
+{
+  "code": 0,
+  "msg": "success",
+  "data": {
+    "name": "demo",
+    "type": "directory",
+    "state": "ready",
+    "url": "https://www.imaoda.com/tt/demo/",
+    "baseUrl": "https://www.imaoda.com/tt/demo/",
+    "remotePath": "/root/repos/tt/demo",
+    "verification": {
+      "state": "passed",
+      "checkedUrl": "https://www.imaoda.com/tt/demo/",
+      "httpStatus": 200
+    }
+  }
+}
+```
+
+只有服务器通过公开 URL 与文件 SHA-256 验收才报告 `ready`；这表示已检查文件
+可访问且内容一致，不能替代浏览器
+渲染和全站资源检查。目录优先使用 `index.html` 或 `index.htm` 作为首页；没有首页
+但含有文件时，`url` 为 `null`，`baseUrl` 保留目录地址，`verification.checkedUrl`
+指向实际检查的文件，AI 不应把目录地址当作已可访问的页面。
+
+文件已经发布但访问检查失败时，返回 `code: 1`、`error.stage`，同时保留
+`data.state: "published"`、URL、远端路径和检查结果，退出码为 1。AI 可以据此继续
+排查访问问题；参数、配置或上传等发布前错误不附带虚构的发布成功数据。
+
+`tt deploy --list` 的 `data` 包含 `catalogUrl` 和
+`directories: [{ "name": "demo", "url": ".../demo/", "hasIndex": true }]`。
+`hasIndex: false` 表示该目录没有首页，链接不保证返回页面。
+
+### 删除文件或项目目录
+
+`tt deploy --delete <name>` 删除 tt 根目录下的一个直接子项，可以是单文件，也可以
+是包含多层内容的整个目录。删除不可恢复，无需交互确认；其他顶层项目保留。
+名称必须是一级名称，不支持 `demo/style.css` 这样的内部路径，不能与本地 source、
+`--name` 或 `--list` 同时使用，且不能删除保留名称 `__catalog`。
+
+删除后刷新目录清单。成功时返回 `code: 0`，`data` 示例：
+
+```json
+{
+  "name": "demo",
+  "type": "directory",
+  "state": "deleted",
+  "remotePath": "/root/repos/tt/demo",
+  "catalogUrl": "https://www.imaoda.com/tt/__catalog/"
+}
+```
+
+目标已不存在时同样成功，返回 `state: "absent"`、`type: null`，便于重复调用。
+若公开目标已删除，但目录清单刷新或私有暂存清理失败，命令返回错误和非零退出码，
+同时保留 `data.state: "deleted"`；AI 应据此排查后续步骤，不能把它理解为目标仍在。
+
 ## Shell 快捷方式
 
 ```bash