pinomad 0.1.0 → 0.1.1

package/README.md

@@ -138,7 +138,39 @@ Restart=always
 WantedBy=multi-user.target
 ```
 
-升级：中继托管的 Web 客户端和宿主版本不一致时，客户端会显示需要更新；两边一起升级——宿主 `pinomad upgrade`，VPS 上 `npm i -g pinomad@latest` 后重启中继。宿主不在中继的 `--allow-host` 里时，宿主日志和 Web 警告会带着要补的 `--allow-host <hostId>`。
+#### 容器平台（Zeabur 等）
+
+镜像在 `deploy/relay/Dockerfile`，装的是锁版本的 npm 发布包（`ARG PINOMAD_VERSION`）。平台终结 TLS 并转发到 `$PORT`（默认 8080），不需要 Caddy。中继把转接状态放在内存里，**只能跑一个实例**，不要开扩容。
+
+| 环境变量 | 含义 |
+|---|---|
+| `PINOMAD_PUBLIC_ORIGIN` | 客户端打开的 https origin，比如 `https://nomad.example.com` |
+| `PINOMAD_ALLOW_HOST` | 允许登记的 hostId，多个用空格分隔（每台宿主上跑 `pinomad relay-id`） |
+| `ZBPACK_DOCKERFILE_PATH=Dockerfile` | **Zeabur 必加**：目录里只有一个 Dockerfile 时，Zeabur 会把它识别成静态站点、用 Caddy 托管文件，中继根本没启动；这个变量强制按 Dockerfile 构建（部署日志里应是 `PLANTYPE=docker`） |
+
+Zeabur 上的步骤（在 Dedicated Server 上部署，用 CLI 上传目录，不接 GitHub）：
+
+```sh
+cd deploy/relay
+zeabur deploy --project-id <项目 id> --create --name pinomad-relay   # 首次：在项目里建出服务
+# 之后重新部署同一个服务：
+zeabur deploy --service-id <服务 id>
+```
+
+然后在服务上配好上面的环境变量（`PORT` 由平台注入，不用自己设），在 Domains 里绑定自定义域名，到 DNS 加一条记录：Dedicated Server 用 **A 记录指向服务器 IP**；Cloudflare 上建议**关掉代理（灰云）**，橙云会让国内访问多绕一圈，证书也由 Zeabur 自己签。域名状态变成 `PROVISIONED` 后，验证：
+
+```sh
+curl -sI https://nomad.example.com/          # 200，中继托管的 Web 客户端
+pinomad service install --relay https://nomad.example.com …   # 宿主接上中继
+```
+
+宿主登记成功会在日志里写一行 `{"event":"relay","status":"registered",…}`，掉线重连时写 `"status":"connecting"`（`pinomad service logs` 查看）；也可以从外面连设备入口 `wss://<origin>/c/<hostId>` 确认：宿主在线时连接保持打开（等握手），没登记会立刻以 `4604`（hostOffline）关闭。
+
+也可以从 GitHub 仓库部署：Root Directory 设 `deploy/relay`、Watch Paths 限 `deploy/relay/**`，其余同上。
+
+#### 升级
+
+中继托管的 Web 客户端和宿主版本不一致时，客户端会显示需要更新；两边一起升级——宿主 `pinomad upgrade`，VPS 上 `npm i -g pinomad@latest` 后重启中继；容器部署则是改 Dockerfile 里的 `PINOMAD_VERSION`，再在 `deploy/relay` 下重新 `zeabur deploy --service-id <服务 id>`（从 GitHub 部署的话合进 main 即触发）。宿主不在中继的 `--allow-host` 里时，宿主日志和 Web 警告会带着要补的 `--allow-host <hostId>`。
 
 npm 装的实例和本机任何开发检出互不相干（各自的数据目录、进程、包路径都独立），所以在同一台机器上开发 PiNomad 不会碰到正在跑的服务。
 
@@ -160,8 +192,9 @@ pinomad upgrade [--force]
 - `restart` 先连上宿主读任务图，有未结束的任务就等它们跑完再重启（Ctrl-C 取消）；`--force` 立即重启，交给 Durable 恢复。打包安装时 `upgrade` 把 `pinomad@latest` 装进运行包所在的 npm 全局前缀（非全局安装会拒绝执行）+ 同样的 restart；源码检出里（`bun run upgrade`）依次 `git pull --ff-only`、`bun install`、`bun run build`，工作区有未提交改动时拒绝执行。前面任何一步失败都直接停下，不重启，服务继续跑旧代码。
 - `uninstall` 只卸载服务，不动数据目录。
 - macOS：宿主以登录会话运行，机器重启后要能自动起来需在系统设置里打开自动登录，并为这台机器关掉睡眠。日志写到 `<数据目录>/logs/host.log`。
-- Linux：要在未登录时也运行需自己执行 `loginctl enable-linger`（install 检测到没开会提示）；日志走 `journalctl --user`。
-- 服务模式下**回环端口也用 HTTP 提供构建好的 Web 客户端**。`pinomad link` 打印的链接按顺序探测：正在跑的 vite 开发服务器（5199）优先；否则宿主自己提供 Web 的端口；都没有则仍是 5199。开发时 `bun run start` + vite 照旧。
+- Linux：要在未登录时也运行需自己执行 `loginctl enable-linger`（install 检测到没开会提示）；日志走 `journalctl --user`。开着 ufw 时，局域网设备访问 `--remote-port` 要先放行，比如 `sudo ufw allow from 192.168.0.0/24 to any port 7422 proto tcp`（只走中继就不用开）。
+- **服务绑定安装时的 node 路径**：单元里写的是 node 和包的绝对路径。用 mise / nvm 管理 Node 时，路径里带着具体版本号（`…/node/26.8.2/…`）；换了 Node 版本、旧目录被删后服务就起不来，要用新版本重新 `npm i -g pinomad`，再跑一次 `pinomad service install …`。`pinomad upgrade` 只升 pinomad，装回原来的前缀，不受影响。
+- 服务模式下**回环端口也用 HTTP 提供构建好的 Web 客户端**。npm 安装时 `pinomad link` 总是指向宿主自己提供的 Web；源码检出里按顺序探测：正在跑的 vite 开发服务器（5199）优先，否则宿主提供 Web 的端口，都没有则仍是 5199。开发时 `bun run start` + vite 照旧。
 - 服务在跑时 `bun run start` 会因为目录锁拿不到而失败（同一数据目录只有一个宿主）；开发时用另一个 `--data-dir`，或先 `uninstall`。
 
 Windows 不在支持范围；其他平台跑 `service` 会直接报错退出。
@@ -173,3 +206,15 @@ bun run typecheck
 bun run test    # vitest + Playwright，首次跑前先 bunx playwright install chromium
 bun run build
 ```
+
+## 发布（ADR-0016）
+
+推 `v*` tag 触发 `.github/workflows/release.yml`：跑完 typecheck / test / build、打包、`npm pack`、装包冒烟后才 `npm publish`。带 `-` 的预发布 tag（`v0.2.0-beta.1`）发到 `next`，正式版发到 `latest`。发布用 npm trusted publishing（OIDC），仓库里没有 npm token。
+
+```sh
+git tag v0.1.1
+git push origin v0.1.1
+```
+
+- 手动发布（流水线不可用时）：`bun run build && bun run package -- --version <v>`，再在 `apps/cli/out` 里 `npm publish`。终端里的 npm 要先 `npm login`（`npm whoami` 能报出用户名）；没登录时 npm 回的是 `404 Not Found` 而不是 401，容易误判成包名问题。
+- 发布后几分钟内 registry 可能还没处理完（新包还会先出现一个 `0.0.0-stage` 占位版本）；这期间查过的机器缓存了旧元数据，安装报 `ETARGET` / "No matching version" 时加 `--prefer-online`。

package/dist/{chunk-srbefzgp.js → chunk-8h3wrn84.js}

@@ -2,12 +2,12 @@
 import {
   restartService,
   serviceManager
-} from "./chunk-928atme2.js";
+} from "./chunk-zx77w1nm.js";
 import {
   globalPrefixOf,
   packageDir,
   packagedVersion
-} from "./chunk-v7yf5752.js";
+} from "./chunk-fpb6f9n5.js";
 import"./chunk-y73t2jmc.js";
 import"./chunk-wgn3cx5q.js";
 import"./chunk-cjfmfyjb.js";

package/dist/{chunk-jew71ysz.js → chunk-9z7echn7.js}

@@ -2,8 +2,8 @@
 import {
   main,
   restartService
-} from "./chunk-928atme2.js";
-import"./chunk-v7yf5752.js";
+} from "./chunk-zx77w1nm.js";
+import"./chunk-fpb6f9n5.js";
 import"./chunk-y73t2jmc.js";
 import"./chunk-wgn3cx5q.js";
 import"./chunk-cjfmfyjb.js";

package/dist/{chunk-v7yf5752.js → chunk-fpb6f9n5.js}

@@ -1,6 +1,6 @@
 // apps/host/src/distribution.ts
 import { fileURLToPath } from "node:url";
-var packagedVersion = "0.1.0";
+var packagedVersion = "0.1.1";
 var webRoot = fileURLToPath(new URL(packagedVersion === undefined ? "../../web/dist" : "../web/", import.meta.url));
 var hostEntry = packagedVersion === undefined ? { script: fileURLToPath(new URL("./main.ts", import.meta.url)), args: [] } : { script: fileURLToPath(new URL("./pinomad.js", import.meta.url)), args: ["host"] };
 var commandHint = (name) => packagedVersion === undefined ? `bun run ${name}` : `pinomad ${name}`;

package/dist/{chunk-hach8mdw.js → chunk-mqbg2cbw.js}

@@ -3,8 +3,9 @@ import {
   serveWebClient
 } from "./chunk-r6w5aqkw.js";
 import {
+  packagedVersion,
   webRoot
-} from "./chunk-v7yf5752.js";
+} from "./chunk-fpb6f9n5.js";
 import {
   PROTOCOL_VERSION,
   UNAUTHORIZED_CLOSE_CODE,
@@ -1446,6 +1447,12 @@ function startRelayLink(options) {
   let delay = minDelay;
   let retryTimer;
   let pendingAccepts = 0;
+  function setState(next) {
+    const changed = state.status !== next.status || state.status === "rejected" && next.status === "rejected" && state.reason !== next.reason;
+    state = next;
+    if (changed)
+      options.onStateChange?.(next);
+  }
   const watched = new Set;
   const ponged = new WeakMap;
   const pingIntervalMs = options.pingIntervalMs ?? 30000;
@@ -1505,7 +1512,7 @@ function startRelayLink(options) {
         break;
       case "registered":
         delay = minDelay;
-        state = { status: "registered" };
+        setState({ status: "registered" });
         break;
       case "incoming": {
         if (pendingAccepts >= maxPendingAccepts)
@@ -1532,14 +1539,12 @@ function startRelayLink(options) {
     const rejection = REJECTION_REASONS[code];
     if (rejection !== undefined) {
       const reason = `relay ${origin}: ${rejection(hostId)} (${code})`;
-      if (state.status !== "rejected" || state.reason !== reason)
-        options.onRejected?.(reason);
-      state = { status: "rejected", reason };
+      setState({ status: "rejected", reason });
       delay = maxDelay;
       reconnect(maxDelay);
       return;
     }
-    state = { status: "connecting" };
+    setState({ status: "connecting" });
     reconnect(delay);
     delay = Math.min(maxDelay, delay * 2);
   }
@@ -1627,17 +1632,25 @@ async function startGateway(options) {
   remote = await startRemote(options, register);
   const secure = options.secure;
   if (secure?.relay !== undefined) {
-    relay = startRelayLink({
+    let link;
+    link = startRelayLink({
       origin: secure.relay.origin,
       signingKey: secure.relay.signingKey,
       accept: (socket) => secureHandshake(socket, secure, options.harness, register),
-      onRejected: (reason) => {
-        broadcast("warning", reason);
-        console.error(reason);
+      onStateChange: (state) => {
+        if (state.status === "registered") {
+          console.log(JSON.stringify({ event: "relay", status: "registered", origin: link.origin, hostId: link.hostId }));
+        } else if (state.status === "connecting") {
+          console.log(JSON.stringify({ event: "relay", status: "connecting", origin: link.origin }));
+        } else {
+          broadcast("warning", state.reason);
+          console.error(state.reason);
+        }
       },
       ...secure.relay.reconnectDelayMs === undefined ? {} : { reconnectDelayMs: secure.relay.reconnectDelayMs },
       ...secure.relay.pingIntervalMs === undefined ? {} : { pingIntervalMs: secure.relay.pingIntervalMs }
     });
+    relay = link;
   }
   return {
     url: `ws://127.0.0.1:${port}`,
@@ -2656,7 +2669,7 @@ async function main(argv) {
   const options = values.faux !== undefined ? fauxOptions(() => () => fauxAssistantMessage(values.faux)) : await piOptions();
   const host = await openHost(options);
   const model = options.initialModel === undefined ? null : `${options.initialModel.provider}/${options.initialModel.modelId}`;
-  const web = "http://127.0.0.1:5199/";
+  const web = packagedVersion === undefined ? "http://127.0.0.1:5199/" : new URL(host.url.replace(/^ws/, "http")).href;
   console.log(JSON.stringify({
     event: "ready",
     url: host.url,

package/dist/{chunk-pkxr5my9.js → chunk-ne6a5q2j.js}

@@ -5,7 +5,7 @@ import {
 import {
   commandHint,
   webRoot
-} from "./chunk-v7yf5752.js";
+} from "./chunk-fpb6f9n5.js";
 import {
   RELAY_CLOSE,
   decodeHostToRelay,

package/dist/{chunk-c3v7vhny.js → chunk-tpd3trvd.js}

@@ -1,6 +1,6 @@
 import {
   packagedVersion
-} from "./chunk-v7yf5752.js";
+} from "./chunk-fpb6f9n5.js";
 import {
   hostAddress
 } from "./chunk-cjfmfyjb.js";

package/dist/{chunk-928atme2.js → chunk-zx77w1nm.js}

@@ -2,7 +2,7 @@ import {
   commandHint,
   hostEntry,
   packagedVersion
-} from "./chunk-v7yf5752.js";
+} from "./chunk-fpb6f9n5.js";
 import {
   connectRemoteDurable
 } from "./chunk-y73t2jmc.js";

package/dist/pinomad.js

@@ -1,18 +1,18 @@
 #!/usr/bin/env node
 import {
   packagedVersion
-} from "./chunk-v7yf5752.js";
+} from "./chunk-fpb6f9n5.js";
 import {
   __require
 } from "./chunk-df32avw6.js";
 
 // apps/cli/src/pinomad.ts
 var COMMANDS = {
-  host: () => import("./chunk-hach8mdw.js"),
-  relay: () => import("./chunk-pkxr5my9.js"),
-  service: () => import("./chunk-jew71ysz.js"),
-  upgrade: () => import("./chunk-srbefzgp.js"),
-  link: () => import("./chunk-c3v7vhny.js"),
+  host: () => import("./chunk-mqbg2cbw.js"),
+  relay: () => import("./chunk-ne6a5q2j.js"),
+  service: () => import("./chunk-9z7echn7.js"),
+  upgrade: () => import("./chunk-8h3wrn84.js"),
+  link: () => import("./chunk-tpd3trvd.js"),
   pair: () => import("./chunk-hsdzb73r.js"),
   "relay-id": () => import("./chunk-7fqn69ys.js")
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pinomad",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "PiNomad — self-hosted coding agent: host, relay, and web client in one package",
   "license": "Apache-2.0",
   "type": "module",