@4pm/cli 0.2.0 → 0.2.2

package/README.md

@@ -1,13 +1,16 @@
 # @4pm/cli
 
-CLI chạy trên máy worker: nhận lệnh từ server và điều phối các CLI AI
-(claude / codex …). Node ESM + TypeScript.
+**Agent chạy trên máy worker** — nhận lệnh từ `@4pm/server` qua WebSocket và điều phối
+các CLI AI (`claude` / `codex`) cùng công cụ khác (`git`, `gh`, `glab`, `shell`).
+Node ESM + TypeScript.
 
-Logic điều phối ở `src/core/`, subcommand ở `src/commands/`, giao tiếp server qua
-`src/services/` (dùng `@4pm/sdk`). Phần dùng chung tách vào `src/common/` (errors,
-logger, io); hàm thuần để ở `src/utils/`.
+Vòng đời: **pairing** với server bằng hashcode (file `.cre`) → xin `ws_token` → mở
+WebSocket TLS → nhận lệnh → **spawn tiến trình con**, gom output (backpressure) trả về
+server. Nhiều instance trên một máy dùng profile riêng, server gom về một **worker**.
 
-> Cây thư mục: xem `README.md` (gốc) § Cấu trúc thư mục.
+```bash
+pnpm --filter @4pm/cli dev
+```
 
-Còn thiếu (thêm khi bắt đầu phát triển): `tsconfig.json`, cấu hình ESLint,
-dependencies (vd `tsx`, thư viện parse CLI).
+> Tổ chức mã, quy ước & phần còn thiếu: [`CLAUDE.md`](./CLAUDE.md).
+> Đặc tả hành vi cli: [`11-docs/61-cli/`](../../11-docs/61-cli/README.md).

package/dist/index.js

@@ -1,4 +1,10 @@
 #!/usr/bin/env node
+import { createRequire as __createRequire } from 'node:module';
+import { fileURLToPath as __fileURLToPath } from 'node:url';
+import { dirname as __pathDirname } from 'node:path';
+const require = __createRequire(import.meta.url);
+const __filename = __fileURLToPath(import.meta.url);
+const __dirname = __pathDirname(__filename);
 var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
@@ -3735,7 +3741,7 @@ function resolveProfile(args) {
   if (index >= 0) {
     const name = args[index + 1];
     if (!name || name.startsWith("--")) {
-      throw new Error("--profile c\u1EA7n k\xE8m t\xEAn profile.");
+      throw new Error("--profile requires a profile name.");
     }
     const rest = [...args.slice(0, index), ...args.slice(index + 2)];
     return [name, rest];
@@ -3881,17 +3887,17 @@ async function fetchCliVersion(serverUrl) {
 async function runLink(serverUrl, profileDir2, profileName) {
   if (readCredential(profileDir2, profileName)) {
     console.log(
-      `Profile "${profileName}" \u0111\xE3 c\xF3 li\xEAn k\u1EBFt (.cre). Ch\u1EA1y \`4pm unlink --profile ${profileName}\` tr\u01B0\u1EDBc n\u1EBFu mu\u1ED1n pair l\u1EA1i.`
+      `Profile "${profileName}" is already linked (.cre). Run \`4pm unlink --profile ${profileName}\` first if you want to pair again.`
     );
     return;
   }
   const hashcode1 = randomBytes(32).toString("hex");
   console.log(`\u2500\u2500 4PM cli pairing (profile: ${profileName}) \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500`);
-  console.log("1. M\u1EDF web 4PM \u2192 /machines, nh\u1EADp hashcode (1):");
+  console.log("1. Open the 4PM web \u2192 /machines, enter hashcode (1):");
   console.log(`
    ${hashcode1}
 `);
-  console.log("2. Web s\u1EBD hi\u1EC3n th\u1ECB hashcode (2) \u2014 d\xE1n v\xE0o \u0111\xE2y.");
+  console.log("2. The web will show hashcode (2) \u2014 paste it here.");
   const rl = createInterface({ input: process.stdin, output: process.stdout });
   const hashcode2 = (await rl.question("hashcode (2): ")).trim();
   rl.close();
@@ -3900,10 +3906,10 @@ async function runLink(serverUrl, profileDir2, profileName) {
     serverUrl,
     hashcode3,
     scope: "unknown",
-    // scope do server quyết theo user pair (ADR-0010)
+    // scope is decided by the server based on the pairing user (ADR-0010)
     pairedAt: (/* @__PURE__ */ new Date()).toISOString()
   });
-  console.log("\u2714 Li\xEAn k\u1EBFt th\xE0nh c\xF4ng \u2014 \u0111\xE3 l\u01B0u .cre. Ch\u1EA1y `4pm start` \u0111\u1EC3 k\u1EBFt n\u1ED1i.");
+  console.log("\u2714 Linked successfully \u2014 saved .cre. Run `4pm start` to connect.");
 }
 
 // src/commands/start.ts
@@ -3924,7 +3930,7 @@ MCowBQYDK2VwAyEARlfzjaFhe5bhRrMp/ZuH6sVqg/S7f8B1dliuF21iDTw=
 `;
 
 // src/version.ts
-var CLI_VERSION = "0.2.0";
+var CLI_VERSION = "0.2.2";
 
 // src/core/update.ts
 function compareSemver(a, b) {
@@ -3944,15 +3950,15 @@ function updateViaNpm(version) {
 }
 async function updateViaDownload(tarballUrl, checksum, signature) {
   const res = await fetch(tarballUrl);
-  if (!res.ok) throw new Error(`T\u1EA3i tarball l\u1ED7i: HTTP ${res.status}`);
+  if (!res.ok) throw new Error(`Failed to download tarball: HTTP ${res.status}`);
   const buf = Buffer.from(await res.arrayBuffer());
   const actual = createHash2("sha256").update(buf).digest("hex");
   if (actual !== checksum) {
-    throw new Error("Checksum tarball kh\xF4ng kh\u1EDBp \u2014 h\u1EE7y update (ADR-0015).");
+    throw new Error("Tarball checksum mismatch \u2014 aborting update (ADR-0015).");
   }
   if (CLI_SIGNING_PUBLIC_KEY) {
     if (!signature) {
-      throw new Error("Thi\u1EBFu ch\u1EEF k\xFD tarball \u2014 h\u1EE7y update (ADR-0015).");
+      throw new Error("Missing tarball signature \u2014 aborting update (ADR-0015).");
     }
     const trimmed = CLI_SIGNING_PUBLIC_KEY.trim();
     const publicKey = trimmed.includes("BEGIN") ? createPublicKey(trimmed) : createPublicKey({
@@ -3962,7 +3968,7 @@ async function updateViaDownload(tarballUrl, checksum, signature) {
     });
     const ok = verify(null, buf, publicKey, Buffer.from(signature, "base64"));
     if (!ok) {
-      throw new Error("Ch\u1EEF k\xFD tarball kh\xF4ng h\u1EE3p l\u1EC7 \u2014 h\u1EE7y update (ADR-0015).");
+      throw new Error("Invalid tarball signature \u2014 aborting update (ADR-0015).");
     }
   }
   const tmp = join3(mkdtempSync(join3(tmpdir(), "4pm-update-")), "cli.tgz");
@@ -3972,12 +3978,33 @@ async function updateViaDownload(tarballUrl, checksum, signature) {
     stdio: "inherit"
   });
 }
+async function updateToLatest(serverUrl) {
+  const meta = await fetchCliVersion(serverUrl);
+  if (compareSemver(CLI_VERSION, meta.latest) >= 0) {
+    return { action: "already-latest", version: CLI_VERSION };
+  }
+  console.log(`Updating ${CLI_VERSION} \u2192 ${meta.latest}\u2026`);
+  try {
+    if (installedViaNpm()) {
+      updateViaNpm(meta.latest);
+    } else {
+      await updateViaDownload(
+        meta.source.tarballUrl,
+        meta.source.checksum,
+        meta.source.signature
+      );
+    }
+    return { action: "updated", version: meta.latest };
+  } catch (err) {
+    return { action: "failed", error: String(err) };
+  }
+}
 async function checkAndUpdate(serverUrl, autoUpdate) {
   let meta;
   try {
     meta = await fetchCliVersion(serverUrl);
   } catch (err) {
-    console.warn(`Kh\xF4ng check \u0111\u01B0\u1EE3c version cli: ${err}`);
+    console.warn(`Could not check cli version: ${err}`);
     return { action: "none" };
   }
   const mandatory = compareSemver(CLI_VERSION, meta.minSupported) < 0;
@@ -3985,12 +4012,12 @@ async function checkAndUpdate(serverUrl, autoUpdate) {
   if (!outdated) return { action: "none" };
   if (!mandatory && !autoUpdate) {
     console.warn(
-      `C\xF3 version m\u1EDBi ${meta.latest} (\u0111ang ch\u1EA1y ${CLI_VERSION}) \u2014 autoUpdate \u0111ang t\u1EAFt.`
+      `A new version ${meta.latest} is available (running ${CLI_VERSION}) \u2014 autoUpdate is off.`
     );
     return { action: "none" };
   }
   console.log(
-    `${mandatory ? "B\u1EAFt bu\u1ED9c" : "T\u1EF1 \u0111\u1ED9ng"} update cli ${CLI_VERSION} \u2192 ${meta.latest}\u2026`
+    `${mandatory ? "Mandatory" : "Automatic"} cli update ${CLI_VERSION} \u2192 ${meta.latest}\u2026`
   );
   try {
     if (installedViaNpm()) {
@@ -4005,10 +4032,10 @@ async function checkAndUpdate(serverUrl, autoUpdate) {
     return { action: "updated", version: meta.latest };
   } catch (err) {
     if (mandatory) {
-      console.error(`Update th\u1EA5t b\u1EA1i: ${err}`);
+      console.error(`Update failed: ${err}`);
       return { action: "blocked", minSupported: meta.minSupported };
     }
-    console.warn(`Update th\u1EA5t b\u1EA1i (b\u1ECF qua \u2014 kh\xF4ng b\u1EAFt bu\u1ED9c): ${err}`);
+    console.warn(`Update failed (skipping \u2014 not mandatory): ${err}`);
     return { action: "none" };
   }
 }
@@ -4056,14 +4083,18 @@ var PermissionCode = {
   // org
   ORG_READ: "org.read",
   ORG_UPDATE: "org.update",
+  // soft-delete the whole org + cancel its subscription (ADMIN only)
+  ORG_DELETE: "org.delete",
   // user
   USER_READ_SELF: "user.read_self",
   USER_LIST: "user.list",
   USER_CREATE: "user.create",
   USER_READ: "user.read",
   USER_UPDATE: "user.update",
+  // ADMIN resets a sub-account's password directly (user-0010)
+  USER_SET_PASSWORD: "user.set_password",
   USER_DELETE: "user.delete",
-  // mời user qua email (ADR-0021)
+  // invite users by email (ADR-0021)
   USER_INVITE: "user.invite",
   // team
   TEAM_LIST: "team.list",
@@ -4085,6 +4116,8 @@ var PermissionCode = {
   PROJECT_DETACH_TEAM: "project.detach_team",
   PROJECT_ATTACH_USER: "project.attach_user",
   PROJECT_DETACH_USER: "project.detach_user",
+  PROJECT_ATTACH_MANAGER: "project.attach_manager",
+  PROJECT_DETACH_MANAGER: "project.detach_manager",
   PROJECT_AI_ASSIST: "project.ai_assist",
   PROJECT_MEMO_READ: "project.memo_read",
   PROJECT_MEMO_WRITE: "project.memo_write",
@@ -4097,7 +4130,7 @@ var PermissionCode = {
   MACHINE_LIST: "machine.list",
   MACHINE_UPDATE: "machine.update",
   MACHINE_UNLINK: "machine.unlink",
-  // gán/gỡ physic project cho cli
+  // assign/detach a cli's physic project
   MACHINE_PHYSIC_MANAGE: "machine.physic_manage",
   // command
   COMMAND_EXECUTE: "command.execute",
@@ -4112,16 +4145,21 @@ var PermissionCode = {
   BILLING_MANAGE: "billing.manage"
 };
 var ALL_PERMISSION_CODES = Object.values(PermissionCode);
+var GrantSubjectType = {
+  USER: "user",
+  TEAM: "team",
+  PROJECT: "project"
+};
 var P = PermissionCode;
 var COMMON = [
   P.AUTH_LOGOUT,
   P.AUTH_CHANGE_PASSWORD,
   P.USER_READ_SELF,
-  // notification của chính mình
+  // one's own notifications
   P.NOTIFICATION_READ
 ];
 var ROLE_DEFAULT_PERMISSIONS = {
-  // ADMIN: full quyền
+  // ADMIN: full permissions
   [Role.ADMIN]: ALL_PERMISSION_CODES,
   [Role.PM]: [
     ...COMMON,
@@ -4150,6 +4188,8 @@ var ROLE_DEFAULT_PERMISSIONS = {
     P.PROJECT_DETACH_TEAM,
     P.PROJECT_ATTACH_USER,
     P.PROJECT_DETACH_USER,
+    P.PROJECT_ATTACH_MANAGER,
+    P.PROJECT_DETACH_MANAGER,
     P.PROJECT_AI_ASSIST,
     P.PROJECT_MEMO_READ,
     P.PROJECT_MEMO_WRITE,
@@ -4195,7 +4235,7 @@ var ROLE_DEFAULT_PERMISSIONS = {
     P.PROJECT_READ,
     P.PROJECT_MEMO_READ,
     P.PROJECT_MEMO_WRITE,
-    // xem worker/cli của mình + setting physic project
+    // view one's own worker/cli + configure the physic project
     P.MACHINE_LIST,
     P.MACHINE_PHYSIC_MANAGE,
     P.COMMAND_EXECUTE,
@@ -4210,8 +4250,70 @@ var PROJECT_SCOPE_CHECKED_CODES = [
   P.PROJECT_DETACH_TEAM,
   P.PROJECT_ATTACH_USER,
   P.PROJECT_DETACH_USER,
+  P.PROJECT_ATTACH_MANAGER,
+  P.PROJECT_DETACH_MANAGER,
   P.PROJECT_AI_ASSIST
 ];
+var SELF_SERVICE_CODES = [
+  P.AUTH_LOGOUT,
+  P.AUTH_CHANGE_PASSWORD,
+  P.USER_READ_SELF,
+  P.NOTIFICATION_READ
+];
+var TEAM_GRANTABLE_CODES = [
+  P.TEAM_READ,
+  P.TEAM_UPDATE,
+  P.TEAM_DELETE,
+  P.TEAM_ATTACH_USER,
+  P.TEAM_DETACH_USER,
+  P.TEAM_ATTACH_PROJECT,
+  P.TEAM_DETACH_PROJECT,
+  P.PROJECT_READ,
+  P.PROJECT_UPDATE,
+  P.PROJECT_ATTACH_TEAM,
+  P.PROJECT_DETACH_TEAM,
+  P.PROJECT_ATTACH_USER,
+  P.PROJECT_DETACH_USER,
+  P.PROJECT_ATTACH_MANAGER,
+  P.PROJECT_DETACH_MANAGER,
+  P.PROJECT_AI_ASSIST,
+  P.PROJECT_MEMO_READ,
+  P.PROJECT_MEMO_WRITE,
+  P.COMMAND_EXECUTE,
+  P.COMMAND_READ,
+  P.MACHINE_LIST,
+  P.MACHINE_PHYSIC_MANAGE
+];
+var PROJECT_GRANTABLE_CODES = [
+  P.PROJECT_READ,
+  P.PROJECT_UPDATE,
+  P.PROJECT_DELETE,
+  P.PROJECT_ATTACH_TEAM,
+  P.PROJECT_DETACH_TEAM,
+  P.PROJECT_ATTACH_USER,
+  P.PROJECT_DETACH_USER,
+  P.PROJECT_ATTACH_MANAGER,
+  P.PROJECT_DETACH_MANAGER,
+  P.PROJECT_AI_ASSIST,
+  P.PROJECT_MEMO_READ,
+  P.PROJECT_MEMO_WRITE,
+  P.COMMAND_EXECUTE,
+  P.COMMAND_READ,
+  P.MACHINE_PHYSIC_MANAGE
+];
+var SELF_SERVICE_SET = new Set(SELF_SERVICE_CODES);
+var TEAM_GRANTABLE_SET = new Set(TEAM_GRANTABLE_CODES);
+var PROJECT_GRANTABLE_SET = new Set(PROJECT_GRANTABLE_CODES);
+function grantSubjectsFor(code) {
+  if (SELF_SERVICE_SET.has(code)) return [];
+  const subjects = [GrantSubjectType.USER];
+  if (TEAM_GRANTABLE_SET.has(code)) subjects.push(GrantSubjectType.TEAM);
+  if (PROJECT_GRANTABLE_SET.has(code)) subjects.push(GrantSubjectType.PROJECT);
+  return subjects;
+}
+var PERMISSION_GRANT_SUBJECTS = Object.fromEntries(
+  ALL_PERMISSION_CODES.map((code) => [code, grantSubjectsFor(code)])
+);
 
 // ../../22-packages/11-shared/11-constants/src/auth.ts
 var ACCESS_TOKEN_TTL_SEC = 60 * 60;
@@ -4310,8 +4412,8 @@ var OutputBatcher = class {
     };
   }
   /**
-   * Nạp thêm output; flush khi đạt ngưỡng; áp backpressure/truncate khi
-   * vượt trần.
+   * Push more output; flush at the threshold; apply backpressure/truncate when
+   * over the cap.
    */
   push(chunk) {
     if (this.buffer.length >= this.opts.maxBufferKb * 1024) {
@@ -4335,7 +4437,7 @@ var OutputBatcher = class {
     }
   }
   /**
-   * Đẩy toàn bộ buffer hiện tại đi ngay (1 batch).
+   * Flush the entire current buffer immediately (one batch).
    */
   flush() {
     if (this.timer) {
@@ -4399,7 +4501,7 @@ async function runCommand(dispatch, emit) {
       emit({
         commandId: dispatch.commandId,
         seq: seq++,
-        chunk: `spawn l\u1ED7i: ${err.message}
+        chunk: `spawn error: ${err.message}
 `,
         done: true,
         exitCode: -1
@@ -4748,13 +4850,13 @@ var WsClient = class {
   heartbeat = null;
   stopped = false;
   credential;
-  /** Output đệm trong lúc mất kết nối (flush khi nối lại). */
+  /** Output buffered while disconnected (flushed on reconnect). */
   offlineBuffer = [];
   offlineBufferBytes = 0;
-  /** Request cli → server đang chờ reply (quota.check — ADR-0020). */
+  /** cli → server requests awaiting a reply (quota.check — ADR-0020). */
   pending = /* @__PURE__ */ new Map();
   /**
-   * Vòng đời chính: connect + reconnect backoff cho tới khi bị revoke.
+   * Main lifecycle: connect + reconnect backoff until revoked.
    */
   async run() {
     for (let attempt = 0; !this.stopped; attempt++) {
@@ -4766,16 +4868,16 @@ var WsClient = class {
           this.logout(err.errorCode);
           return;
         }
-        console.error(`K\u1EBFt n\u1ED1i l\u1ED7i: ${err}`);
+        console.error(`Connection error: ${err}`);
       }
       if (this.stopped) return;
       const wait = backoffJitterMs(Math.min(attempt, 6), 1e3, 6e4);
-      console.log(`K\u1EBFt n\u1ED1i l\u1EA1i sau ${Math.round(wait / 1e3)}s\u2026`);
+      console.log(`Reconnecting in ${Math.round(wait / 1e3)}s\u2026`);
       await sleep(wait);
     }
   }
   /**
-   * 1 phiên WS: token → connect → handshake → xử lý message tới khi đóng.
+   * One WS session: token → connect → handshake → handle messages until close.
    */
   connectOnce() {
     return new Promise((resolve5, reject) => {
@@ -4802,14 +4904,14 @@ var WsClient = class {
           try {
             this.handleMessage(JSON.parse(String(raw)));
           } catch (err) {
-            console.error(`Message l\u1ED7i: ${err}`);
+            console.error(`Message error: ${err}`);
           }
         });
         socket.on("close", (code) => {
           this.clearHeartbeat();
           this.sessionKey = null;
           if (code === CLOSE_DRAINING) {
-            console.log("Server draining \u2014 s\u1EBD k\u1EBFt n\u1ED1i l\u1EA1i (backoff + jitter).");
+            console.log("Server draining \u2014 will reconnect (backoff + jitter).");
           }
           resolve5();
         });
@@ -4821,13 +4923,13 @@ var WsClient = class {
     });
   }
   /**
-   * Xử lý control message (hello_ack/error) và envelope kênh.
+   * Handle control messages (hello_ack/error) and channel envelopes.
    */
   handleMessage(message) {
     if ("type" in message) {
       if (message.type === "hello_ack" && this.ecdh) {
         this.sessionKey = deriveSessionKey(this.ecdh, message.pubkey);
-        console.log("\u2714 \u0110\xE3 k\u1EBFt n\u1ED1i server (m\xE3 h\xF3a phi\xEAn s\u1EB5n s\xE0ng).");
+        console.log("\u2714 Connected to the server (session encryption ready).");
         this.sendMachineStatus();
         this.flushOfflineBuffer();
         this.startHeartbeat();
@@ -4840,11 +4942,11 @@ var WsClient = class {
         }
         if (message.errorCode === "CLI_VERSION_UNSUPPORTED") {
           this.stopped = true;
-          console.error(`Server t\u1EEB ch\u1ED1i version cli (${message.message}) \u2014 h\xE3y update.`);
+          console.error(`Server rejected the cli version (${message.message}) \u2014 please update.`);
           this.socket?.close();
           return;
         }
-        console.warn(`Server b\xE1o l\u1ED7i: ${message.errorCode}`);
+        console.warn(`Server reported an error: ${message.errorCode}`);
         this.socket?.close();
         return;
       }
@@ -4927,9 +5029,9 @@ var WsClient = class {
     }
   }
   /**
-   * Gửi 1 envelope (payload mã hóa + wsToken từng message — arch 0004).
-   * Mất kết nối: output lệnh đang chạy giữ trong buffer (trần 512KB,
-   * bỏ cũ nhất) rồi flush khi nối lại.
+   * Send one envelope (encrypted payload + per-message wsToken — arch 0004).
+   * When disconnected: the running command's output is held in a buffer (512KB cap,
+   * dropping the oldest) then flushed on reconnect.
    */
   send(channel, data, replyTo = null) {
     if (!this.socket || !this.sessionKey) {
@@ -4948,13 +5050,13 @@ var WsClient = class {
     this.socket.send(JSON.stringify(envelope));
   }
   /**
-   * Request cli → server và chờ reply theo id envelope (timeout 15s).
-   * Dùng cho quota.check trước khi spawn AI cli (ADR-0020).
+   * Send a cli → server request and await the reply by envelope id (15s timeout).
+   * Used for quota.check before spawning an AI cli (ADR-0020).
    */
   request(channel, data) {
     return new Promise((resolve5, reject) => {
       if (!this.socket || !this.sessionKey) {
-        reject(new Error("Ch\u01B0a k\u1EBFt n\u1ED1i server."));
+        reject(new Error("Not connected to the server."));
         return;
       }
       const { payload, nonce } = encryptPayload(this.sessionKey, data);
@@ -4968,7 +5070,7 @@ var WsClient = class {
       };
       const timer = setTimeout(() => {
         this.pending.delete(envelope.id);
-        reject(new Error("Server kh\xF4ng tr\u1EA3 l\u1EDDi (timeout)."));
+        reject(new Error("Server did not respond (timeout)."));
       }, 15e3);
       timer.unref?.();
       this.pending.set(envelope.id, {
@@ -4978,16 +5080,16 @@ var WsClient = class {
       this.socket.send(JSON.stringify(envelope));
     });
   }
-  /** quota.check trước khi spawn AI cli (ADR-0020). */
+  /** quota.check before spawning an AI cli (ADR-0020). */
   checkQuota(metric, amount = 1) {
     return this.request(WsChannels.QUOTA_CHECK, { metric, amount });
   }
-  /** usage.report batch về server (ADR-0020). */
+  /** usage.report batched to the server (ADR-0020). */
   reportUsage(events) {
     this.send(WsChannels.USAGE_REPORT, { events });
   }
   /**
-   * Đệm output khi offline (trần bytes — bỏ message cũ nhất khi vượt).
+   * Buffer output while offline (byte cap — drop the oldest message when exceeded).
    */
   bufferOffline(channel, data) {
     const bytes = JSON.stringify(data).length;
@@ -4999,7 +5101,7 @@ var WsClient = class {
     }
   }
   /**
-   * Flush buffer output sau khi handshake lại thành công.
+   * Flush the output buffer after a successful re-handshake.
    */
   flushOfflineBuffer() {
     const queued = this.offlineBuffer.splice(0);
@@ -5007,8 +5109,8 @@ var WsClient = class {
     for (const item of queued) this.send(item.channel, item.data);
   }
   /**
-   * Báo machine.status: version + trạng thái physic project đang phục vụ
-   * (path, folder tồn tại?, autonomous).
+   * Report machine.status: version + the state of the physic project being served
+   * (path, does the folder exist?, autonomous).
    */
   sendMachineStatus() {
     const config = readProfileConfig(this.context.profileDir);
@@ -5022,7 +5124,7 @@ var WsClient = class {
       autonomousRunning: false
     });
   }
-  /** Heartbeat 30s: ping + báo lại machine.status định kỳ. */
+  /** Heartbeat every 30s: ping + periodically re-report machine.status. */
   startHeartbeat() {
     this.clearHeartbeat();
     this.heartbeat = setInterval(() => {
@@ -5036,14 +5138,14 @@ var WsClient = class {
     this.heartbeat = null;
   }
   /**
-   * Logout: đóng WS, xóa `.cre`, hướng dẫn pair lại (state Unlinked).
+   * Logout: close WS, delete `.cre`, and prompt to pair again (Unlinked state).
    */
   logout(reason) {
     this.stopped = true;
     this.clearHeartbeat();
     this.socket?.close();
     deleteCredential(this.context.profileDir);
-    console.error(`Li\xEAn k\u1EBFt kh\xF4ng c\xF2n hi\u1EC7u l\u1EF1c (${reason}) \u2014 \u0111\xE3 x\xF3a .cre. Ch\u1EA1y \`4pm link\` \u0111\u1EC3 pair l\u1EA1i.`);
+    console.error(`Link is no longer valid (${reason}) \u2014 deleted .cre. Run \`4pm link\` to pair again.`);
   }
 };
 
@@ -5052,7 +5154,7 @@ async function runStart(profileDir2, profileName) {
   const credential = readCredential(profileDir2, profileName);
   if (!credential) {
     console.error(
-      `Profile "${profileName}" ch\u01B0a li\xEAn k\u1EBFt \u2014 ch\u1EA1y \`4pm link --server <URL>\` tr\u01B0\u1EDBc.`
+      `Profile "${profileName}" is not linked \u2014 run \`4pm link --server <URL>\` first.`
     );
     process.exitCode = 1;
     return;
@@ -5062,13 +5164,13 @@ async function runStart(profileDir2, profileName) {
   const result = await checkAndUpdate(credential.serverUrl, autoUpdate);
   if (result.action === "blocked") {
     console.error(
-      `CLI c\u0169 h\u01A1n minSupported (${result.minSupported}) v\xE0 update th\u1EA5t b\u1EA1i \u2014 kh\xF4ng th\u1EC3 connect.`
+      `CLI is older than minSupported (${result.minSupported}) and the update failed \u2014 cannot connect.`
     );
     process.exitCode = 1;
     return;
   }
   if (result.action === "updated") {
-    console.log("Kh\u1EDFi \u0111\u1ED9ng l\u1EA1i v\u1EDBi version m\u1EDBi\u2026");
+    console.log("Restarting with the new version\u2026");
     const child = spawn2(process.execPath, process.argv.slice(1), {
       stdio: "inherit",
       env: { ...process.env, FOURPM_NO_UPDATE: "1" }
@@ -5077,7 +5179,7 @@ async function runStart(profileDir2, profileName) {
     return;
   }
   initCommandHistory(profileDir2, profileName, config.commandHistoryUploadMinutes ?? 10);
-  console.log(`K\u1EBFt n\u1ED1i t\u1EDBi ${credential.serverUrl} (profile: ${profileName})\u2026`);
+  console.log(`Connecting to ${credential.serverUrl} (profile: ${profileName})\u2026`);
   await new WsClient({
     credential,
     machine: collectFingerprint(),
@@ -5088,11 +5190,52 @@ async function runStart(profileDir2, profileName) {
 // src/commands/unlink.ts
 function runUnlink(profileDir2, profileName) {
   if (!readCredential(profileDir2, profileName)) {
-    console.log(`Profile "${profileName}" ch\u01B0a c\xF3 li\xEAn k\u1EBFt n\xE0o.`);
+    console.log(`Profile "${profileName}" has no link yet.`);
     return;
   }
   deleteCredential(profileDir2);
-  console.log("\u2714 \u0110\xE3 x\xF3a .cre \u2014 h\u1EE7y li\xEAn k\u1EBFt ph\xEDa server \u1EDF web /machines.");
+  console.log("\u2714 Deleted .cre \u2014 revoke the server-side link at web /machines.");
+}
+
+// src/commands/update.ts
+async function runUpdate(profileDir2, profileName, serverUrlFlag) {
+  const serverUrl = (serverUrlFlag ?? readCredential(profileDir2, profileName)?.serverUrl ?? process.env.FOURPM_SERVER ?? "http://localhost:3001").replace(/\/$/, "");
+  let result;
+  try {
+    result = await updateToLatest(serverUrl);
+  } catch (err) {
+    console.error(`Could not check for updates: ${err}`);
+    process.exitCode = 1;
+    return;
+  }
+  switch (result.action) {
+    case "already-latest":
+      console.log(`Already up to date (${result.version}).`);
+      break;
+    case "updated":
+      console.log(`\u2714 Updated to ${result.version}. Run \`4pm start\` to reconnect.`);
+      break;
+    case "failed":
+      console.error(`Update failed: ${result.error}`);
+      process.exitCode = 1;
+      break;
+  }
+}
+
+// src/commands/version.ts
+async function runVersion(profileDir2, profileName, serverUrlFlag) {
+  console.log(`4pm cli ${CLI_VERSION}`);
+  const serverUrl = serverUrlFlag ?? readCredential(profileDir2, profileName)?.serverUrl ?? process.env.FOURPM_SERVER;
+  if (!serverUrl) return;
+  try {
+    const meta = await fetchCliVersion(serverUrl.replace(/\/$/, ""));
+    const outdated = compareSemver(CLI_VERSION, meta.latest) < 0;
+    const hint = outdated ? "  (update available \u2014 run `4pm update`)" : "  (up to date)";
+    console.log(`latest:  ${meta.latest}${hint}`);
+    console.log(`minSupported: ${meta.minSupported}`);
+  } catch (err) {
+    console.warn(`Could not reach the server for the latest version: ${err}`);
+  }
 }
 
 // src/index.ts
@@ -5116,17 +5259,28 @@ async function main() {
     case "unlink":
       runUnlink(dir, profileName);
       break;
+    case "version":
+    case "--version":
+    case "-v":
+      await runVersion(dir, profileName, flagValue(rest, "server"));
+      break;
+    case "update":
+    case "upgrade":
+      await runUpdate(dir, profileName, flagValue(rest, "server"));
+      break;
     default:
       console.log(
         [
-          "4pm \u2014 CLI m\xE1y worker c\u1EE7a 4PM",
+          "4pm \u2014 the 4PM worker-machine CLI",
           "",
-          "C\xE1ch d\xF9ng:",
-          "  4pm [--profile <t\xEAn>] link [--server URL]   Pairing v\u1EDBi server (hashcode 1\u21922\u21923)",
-          "  4pm [--profile <t\xEAn>] start                 K\u1EBFt n\u1ED1i WS, nh\u1EADn l\u1EC7nh t\u1EEB server",
-          "  4pm [--profile <t\xEAn>] unlink                X\xF3a credential c\u1EE5c b\u1ED9 (.cre)",
+          "Usage:",
+          "  4pm [--profile <name>] link [--server URL]   Pair with the server (hashcode 1\u21922\u21923)",
+          "  4pm [--profile <name>] start                 Connect WS, receive commands from the server",
+          "  4pm [--profile <name>] unlink                Delete the local credential (.cre)",
+          "  4pm version [--server URL]                   Show the installed version (+ latest from the server)",
+          "  4pm update  [--server URL]                   Update to the latest version now",
           "",
-          "Kh\xF4ng c\xF3 --profile \u21D2 profile `default` (ADR-0014)."
+          "Without --profile \u21D2 the `default` profile (ADR-0014)."
         ].join("\n")
       );
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@4pm/cli",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "private": false,
   "description": "4PM CLI — drives Claude/Codex CLIs on AI worker machines (Node + TypeScript)",
   "type": "module",