maoda-commander-tt 0.0.46 → 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 查找
@@ -58,6 +59,227 @@ pnpm build
 pnpm start -- --help
 ```
 
+## 发布到 npm
+
+发布采用 GitHub Actions + npm Trusted Publishing（OIDC）。本地 `pnpm pub` 负责
+检查、递增 patch 版本、提交版本和推送 `tt-v<版本>` 标签；GitHub Actions 在
+`template-commander/` 中重新安装依赖、测试、构建，再发布 `maoda-commander-tt`。
+
+### 首次配置
+
+1. 将本次改造提交到 `main` 并推送到 `imaoda/local-multi-repo`，确保仓库根目录的
+   `.github/workflows/publish-tt.yml` 已在 GitHub 上，且仓库已启用 Actions。
+2. 登录 [npm 包设置](https://www.npmjs.com/package/maoda-commander-tt/access)，
+   在 Trusted publishing 中添加 GitHub Actions，填写：
+
+   | 字段 | 值 |
+   |---|---|
+   | Organization or user | `imaoda` |
+   | Repository | `local-multi-repo` |
+   | Workflow filename | `publish-tt.yml` |
+   | Environment name | 留空 |
+   | Allowed actions | 允许直接执行 `npm publish` |
+
+   Workflow filename 只填文件名。只允许 `npm stage publish` 时，发布仍需人工批准。
+   保存信任配置时需完成一次 npm 账号验证，后续工作流发布使用 OIDC，无需配置
+   `NPM_TOKEN` 或逐次登录 npm。
+3. 按下面的日常流程发布，在 GitHub Actions 中确认第一次发布成功。
+
+网页保存异常时，也可以使用官方 CLI 配置同一个信任关系（终端登录及配置时
+按 npm 提示完成账号验证）：
+
+```bash
+npm exec --yes --package=npm@11.16.0 -- npm login --registry=https://registry.npmjs.org
+npm exec --yes --package=npm@11.16.0 -- npm trust github maoda-commander-tt \
+  --repo imaoda/local-multi-repo --file publish-tt.yml --allow-publish --yes \
+  --registry=https://registry.npmjs.org
+```
+
+工作流使用 GitHub 托管的 runner、Node.js 24、npm 11.16.0 和 pnpm 11.1.2，
+并固定第三方 Action 的提交 SHA。当前 GitHub 仓库为私有仓库，因此不会生成
+npm provenance；这不影响 OIDC 发布。
+
+### 日常发布
+
+由 agent 代办时，直接说“发布 tt”即可；agent 按
+[发布 harness](AGENTS.md) 执行检查、发布、等待 npm 目标版本可用，并在本机
+全局安装该精确版本、验证 `tt --version`。无需用户自行执行下面的命令。
+
+先提交代码，确保整个 Git 仓库没有未提交或未跟踪的文件，并切换到 `main`。
+本地 `main` 可以有尚未推送的提交，但不能落后于远端或与远端分叉。
+
+```bash
+cd ~/work/local-multi-repo/template-commander
+pnpm pub
+```
+
+命令会运行源码测试、发布脚本测试、构建和 CLI 帮助检查，然后只修改本包的
+`package.json` 版本、创建发布提交和带注释的 `tt-v<版本>` 标签，原子推送
+`main` 与这个标签。其他包的标签不会随之推送。CI 会校验标签与包版本一致；
+普通代码推送不会触发 npm 发布。
+
+推送成功表示已触发 CI，最终结果以
+[Publish tt 工作流](https://github.com/imaoda/local-multi-repo/actions/workflows/publish-tt.yml)
+为准。等待本次发布结束再发布下一版；GitHub 的并发队列可能替换尚未开始的
+发布任务。发布后，在需要更新本机全局 `tt` 的电脑上运行 `pnpm upd`。
+
+### 失败后继续
+
+- 本地检查失败：先修复并提交，再运行 `pnpm pub`；检查失败不会递增版本。
+- 推送失败但发布提交和标签已生成：按终端提示修复网络或权限，在原发布提交上
+  运行 `pnpm pub --retry`，重推同一版本，避免再次递增。
+- 推送成功但 CI 失败：若只是 npm 信任配置错误，修正后在 Actions 中重跑失败的
+  工作流；若需修改代码，提交修复后通过 `pnpm pub` 发布新版本。
+
+不要在 CI 中运行 `pnpm pub`：它负责本地版本提交和推送，CI 的最终发布步骤是
+`npm publish`。已发布的版本不能重复发布。
+
+参见 [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
+# 在 ~/work/web-proxy 中先执行 w2 start，成功后执行 pnpm gateway
+tt sc w2
+```
+
+命令日志直接输出到当前终端，gateway 在前台运行。
+
 ## AI 音频生成
 
 `ai audio` 接受一段自然语言提示词并等待 XYQ 返回 MP3。参考音频可选；提供时，
@@ -187,6 +409,10 @@ return missingNameError();
 | `pnpm build` | TypeScript 编译 |
 | `pnpm start` | 运行编译后产物 |
 | `pnpm clean` | 清理 dist 目录 |
+| `pnpm test:release` | 在临时 Git 仓库中验证发布脚本 |
+| `pnpm pub` | 检查、升 patch 版本并推送 tt 标签，触发 CI 发布 |
+| `pnpm pub --retry` | 重推当前发布提交和标签，不递增版本 |
+| `pnpm upd` | 将本机全局 tt 更新到 npm 上的最新版本 |
 
 ## 技术栈