From 67528dde5fcd1bc7ab2198b728486acda0fa8ed4 Mon Sep 17 00:00:00 2001
From: Jeffery <jiantw83@yahoo.com>
Date: Thu, 17 Sep 2026 15:30:27 +0800
Subject: [PATCH] =?UTF-8?q?fix(README):=20=E5=AE=89=E8=A3=9D=E6=8C=87?=
 =?UTF-8?q?=E4=BB=A4=E8=A3=9C=E4=B8=8A=20git+=20=E5=89=8D=E7=B6=B4?=
 =?UTF-8?q?=EF=BC=8C=E5=90=A6=E5=89=87=20npm=20=E6=9C=83=E6=8A=8A=E5=AE=83?=
 =?UTF-8?q?=E7=95=B6=E5=A3=93=E7=B8=AE=E6=AA=94?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

npm 只有看到 git/git+ssh/git+http/git+https/git+file 才會當成 git repo。
寫成 https://….git 會被歸類成遠端 tarball，下載回來解壓失敗，錯誤是
TAR_BAD_ARCHIVE: Unrecognized archive format——看起來完全不像「網址寫法錯了」，
使用者只會以為套件壞了。

先前那條「README 指令逐字執行得動」的測試沒抓到，因為它只跑 tea-sdlc 開頭的
行，npm 那行從來沒被執行過。補一條規則把 .git 網址必須帶 git+ 前綴釘住：
真的去跑一次 npm 全域安裝要開網路、要三秒，不適合放進這套向來密封的測試裡，
但「前綴在不在」這條規則本身就足以擋掉這個錯。

議題 #25

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 README.md                   |  7 +++++--
 test/readme-install.test.js | 13 +++++++++++--
 2 files changed, 16 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index e1cee56..63868ff 100644
--- a/README.md
+++ b/README.md
@@ -67,11 +67,14 @@ tea-sdlc/
 一行裝好，終端機就多出一個 `tea-sdlc` 指令：
 
 ```bash
-npm i -g https://gitea.jsc.idv.tw/plugins/tea-sdlc.git
+npm i -g git+https://gitea.jsc.idv.tw/plugins/tea-sdlc.git
 ```
 
 要裝特定版本就在網址後面接上 tag：`...tea-sdlc.git#v0.1.0`。不必設定任何 registry 或憑證。
 
+> `git+` 前綴不能省。npm 只有看到 `git+https://` 才會當成 git repo；寫成 `https://….git`
+> 會被當成遠端壓縮檔下載，然後以 `TAR_BAD_ARCHIVE: Unrecognized archive format` 失敗。
+
 接著把六個流程指令佈署到你裝了的每個 agent 平台：
 
 ```bash
@@ -114,7 +117,7 @@ tea-sdlc install --dry-run
 
 | 想做的事 | 指令 |
 | --- | --- |
-| 更新到最新版 | `npm i -g https://gitea.jsc.idv.tw/plugins/tea-sdlc.git` |
+| 更新到最新版 | `npm i -g git+https://gitea.jsc.idv.tw/plugins/tea-sdlc.git` |
 | 指令數量變了之後重新佈署 | `tea-sdlc install` |
 | 查目前版本、正本位置與環境 | `tea-sdlc status` |
 | 只移除轉接檔（正本不動） | `tea-sdlc uninstall` |
diff --git a/test/readme-install.test.js b/test/readme-install.test.js
index deb3920..ef4f43a 100644
--- a/test/readme-install.test.js
+++ b/test/readme-install.test.js
@@ -27,15 +27,24 @@ test('安裝以 npm 為唯一建議路徑，指令含完整可複製的 git URL'
 
   assert.equal(install.length > 0, true, 'README 沒有 npm 安裝指令');
   assert.ok(
-    install.some((line) => line.includes('https://gitea.jsc.idv.tw/plugins/tea-sdlc.git')),
+    install.some((line) => line.includes('gitea.jsc.idv.tw/plugins/tea-sdlc.git')),
     `安裝指令少了完整 git URL：${install.join(' / ')}`,
   );
 });
 
+test('指向 .git 的安裝指令一律帶 git+ 前綴，否則 npm 會把它當壓縮檔去解', () => {
+  // npm 只有看到 git/git+ssh/git+http/git+https/git+file 才會當成 git repo；
+  // 純 https://….git 會被歸類成遠端 tarball，下載回來解壓失敗，錯誤訊息是
+  // TAR_BAD_ARCHIVE: Unrecognized archive format——看起來完全不像「網址寫法錯了」。
+  for (const line of commands(readme()).filter((l) => l.startsWith('npm i -g') && l.includes('.git'))) {
+    assert.match(line, /git\+https:\/\//, `這行 npm 跑不起來：${line}`);
+  }
+});
+
 test('更新與移除各有完整指令表，順序講清楚先 uninstall 再 npm rm', () => {
   const text = readme();
 
-  assert.match(text, /npm i -g https:\/\/gitea\.jsc\.idv\.tw\/plugins\/tea-sdlc\.git/);
+  assert.match(text, /npm i -g git\+https:\/\/gitea\.jsc\.idv\.tw\/plugins\/tea-sdlc\.git/);
   assert.match(text, /tea-sdlc uninstall/);
   assert.match(text, /npm rm -g tea-sdlc/);
   // 先砍套件就再也刪不掉那些孤兒轉接檔，順序本身就是內容