@loviusc/sa-spec 0.2.5 → 0.2.7

package/readme.md

@@ -32,6 +32,7 @@ sa-spec init --full
 - `spec:propose` (`scp`) $\to$ **AI 自動建立 feature 分支與草稿目錄**（零手動指令）
 - `spec:analyze` (`sca`) $\to$ AI 衝突檢查並產出規格文件草稿
 - `spec:commit` (`scc`) $\to$ **AI 自動向主分支領取新號並自動合併回主分支！**
+- `spec:pdf` (`spd`) $\to$ **一鍵將單一 `.md` 或整個需求規格書轉為高品質 PDF！**
 
 👉 **Language Guides: [English](./README.en.md) | [繁體中文](./README.zh-TW.md) | [简体中文](./README.zh-CN.md) | [日本語](./README.ja.md) | [한국어](./README.ko.md)**
 
@@ -39,7 +40,7 @@ sa-spec init --full
 
 `sa-spec` 是一個輕量的系統分析文件工作台，用固定流程把需求想法整理成可確認、可歸檔、可檢查的文件。
 
-AI 工作流只使用四個指令，並支援簡寫別名（兩者等價）：
+AI 工作流使用五個指令，並支援簡寫別名（兩者等價）：
 
 | 標準指令 | 簡寫 | 說明 |
 |---|---|---|
@@ -47,6 +48,7 @@ AI 工作流只使用四個指令，並支援簡寫別名（兩者等價）：
 | `spec:propose` | `scp` | 提出需求並整理摘要 |
 | `spec:analyze` | `sca` | 衝突檢查與規格起草 |
 | `spec:commit` | `scc` | 確認歸檔並建立 Git commit |
+| `spec:pdf` | `spd` | 將指定 `.md` 或需求目錄匯出為 PDF |
 
 每個需求歸檔後固定包含：
 
@@ -96,6 +98,25 @@ npm --version
 git --version
 ```
 
+## 一鍵腳本管理（安裝 / 更新 / 解除安裝）
+
+專案內建獨立的跨平台腳本，直接執行對應檔案即可完成安裝、更新或解除安裝：
+
+### macOS / Linux (`.sh`)
+```bash
+./install.sh      # 安裝 sa-spec
+./update.sh       # 更新 sa-spec 至最新版本
+./uninstall.sh    # 解除安裝 sa-spec
+```
+
+### Windows (`.bat`)
+可直接雙擊執行，或在 CMD / PowerShell 輸入：
+```bat
+install.bat       &:: 安裝 sa-spec
+update.bat        &:: 更新 sa-spec 至最新版本
+uninstall.bat     &:: 解除安裝 sa-spec
+```
+
 ## macOS 安裝
 
 使用 npm 安裝：
@@ -275,6 +296,7 @@ sa-spec init --full
 | `sa-spec init [--full] [--lang zh-TW|en|zh-CN|ja|ko]` | 建立文件骨架與規則文件（支援 5 種語言，預設 `zh-TW`）。 |
 | `sa-spec new [--id REQ-001] --name login [--branch]` | 建立需求資料夾與空白文件模板（未帶 `--id` 時啟用多人草稿模式，可選 `--branch` 自動建立並切換至 `feat/<name>` 分支）。 |
 | `sa-spec finalize --name login` | 將草稿需求定號歸檔為最新序號（自動計算最新號碼、重命名目錄、批次置換 `{{REQ_ID}}` 並重建索引）。 |
+| `sa-spec pdf <target> [--split] [--output out.pdf]` | 將指定 `.md` 轉為同名 `.pdf`，或將需求編號/目錄（如 `REQ-001`）整包合併匯出成一份完整規格書 PDF（加 `--split` 則各檔獨立轉出，`--all` 匯出全專案）。 |
 | `sa-spec reindex` | 掃描 `project/REQ-*` 目錄，依序號重新生成乾淨無衝突的 `project/index.md`。 |
 | `sa-spec check` | 檢查基本文件是否存在。 |
 | `sa-spec status` | 顯示系統規格與需求索引狀態。 |
@@ -324,6 +346,7 @@ Markdown、PlantUML、YAML、GitLens 這類套件可以提升閱讀與檢查體
 | AI 工作流程 | `spec:propose` / `scp` | VS Code AI 對話側邊欄 | 整理使用者提出的需求。 |
 | AI 工作流程 | `spec:analyze` / `sca` | VS Code AI 對話側邊欄 | 檢查衝突並產出待確認草稿。 |
 | AI 工作流程 | `spec:commit` / `scc` | VS Code AI 對話側邊欄 | 歸檔已確認版本並建立本機 Git commit。 |
+| AI 工作流程 | `spec:pdf` / `spd` | VS Code AI 對話側邊欄 | 將指定 `.md` 或需求目錄匯出為 PDF 規格書。 |
 
 建議操作順序：
 
@@ -353,6 +376,7 @@ spec:commit  # 或簡寫 scc
 | `spec:propose` | `scp` | 使用者提出需求後，整理需求摘要、目標、初步流程與待確認事項。 |
 | `spec:analyze` | `sca` | 檢查是否與既有需求衝突；無衝突才產出 SRS、UML、OpenAPI、DB Schema 草稿。 |
 | `spec:commit` | `scc` | 使用者確認無衝突版本後，將版本歸檔到 `project/`，並建立本機 Git commit。 |
+| `spec:pdf` | `spd` | 將指定的 `.md` 檔或需求（如 `REQ-001`）匯出為高品質 PDF。 |
 
 狀態機：
 
@@ -385,7 +409,7 @@ commit (scc) -> 歸檔 -> 本機 Git commit
 docs(REQ-001): 番茄時鐘 - 新增專注與休息計時需求
 ```
 
-只有在使用者明確要求推送 remote，或專案設定啟用 auto-push 時，才會執行 `git push`。如果 push 失敗，只回報認證或網路問題，不會回滾已完成的文件歸檔與本機 commit。
+**鐵律**：只要 Git repository 有設定 remote（例如 `origin`），在 `scp` 建立分支與 `scc` 歸檔合併時，都會**自動執行 `git push` 推送至 remote**。如果 push 失敗，只回報認證或網路問題，不會回滾已完成的文件歸檔與本機 commit。
 
 ## 多人協作解決方案（Git-Flow 與延遲綁定 ID）
 
@@ -397,12 +421,12 @@ docs(REQ-001): 番茄時鐘 - 新增專注與休息計時需求
 
 ```mermaid
 flowchart TD
-    A["開新需求: scp 或 sa-spec new --branch"] --> B["建立並切換至 feat/cart 分支<br/>以 project/cart/ 建立草稿目錄"]
+    A["開新需求: scp 或 sa-spec new --branch"] --> B["建立並切換至 feat/cart 分支<br/>若有 remote 自動推分支至遠端<br/>以 project/cart/ 建立草稿目錄"]
     B --> C["AI 分析與起草: sca<br/>內部使用 {{REQ_ID}} 佔位<br/>自動同步 master 規格防護"]
     C --> D{"使用者確認通過<br/>執行 scc 或 finalize"}
-    D --> E["自動查詢主分支最新序號 N"]
+    D --> E["先推分支至 remote 並同步遠端狀態<br/>再查詢主分支最新序號 N"]
     E --> F["自動定號為 project/REQ-N+1-cart/<br/>批次置換 {{REQ_ID}} 並建立 commit"]
-    F --> G["自動合併至 master 主分支<br/>動態重新生成 project/index.md"]
+    F --> G["自動合併至 master 主分支並推上 remote<br/>動態重新生成 project/index.md"]
     G --> H["完成閉環：零衝突、序號永遠連續！"]
 ```
 
@@ -415,7 +439,7 @@ flowchart TD
   ```text
   scp 購物車結帳需求
   ```
-  AI 收到後，會**自動在背景執行 `git checkout -b feat/cart-checkout` 建立並切換分支**，並在 `project/cart-checkout/` 建立草稿目錄！
+  AI 收到後，會**自動在背景執行 `git checkout -b feat/cart-checkout` 建立並切換分支**，檢查若有設定 Git remote 則自動將分支推上遠端（`git push -u origin feat/cart-checkout`），並在 `project/cart-checkout/` 建立草稿目錄！
 * **方式 B（CLI 終端指令）**：
   ```bash
   sa-spec new --name cart-checkout --branch
@@ -425,7 +449,7 @@ flowchart TD
 #### 2. 分析與衝突檢查（規格基線同步）
 在分支上執行 `spec:analyze`（或 `sca`）前，工具會確認已取得 `master`（或 `origin/master`）的最新規格，確保是以全專案最新基準進行影響評估，避免因分支落後而漏檢權限、API 或資料表衝突。
 
-#### 3. 確認歸檔與延遲定號（自動領號 + 自動合併回主分支）
+#### 3. 確認歸檔與延遲定號（先推分支 + 自動領號 + 自動合併並推上 Remote）
 當需求規格經使用者確認無誤，準備歸檔時：
 
 * **方式 A（純 AI 自動化，最推薦）**：在 AI 側邊欄直接輸入：
@@ -433,15 +457,16 @@ flowchart TD
   scc
   ```
   AI 收到後會自動完成全自動 Git-Flow 閉環作業：
-  1. **自動向主分支查詢並取得新號**：查詢 master/main 目前最大序號（例如最大是 `REQ-005`，自動領取最新號 `REQ-006`），避免號碼競爭。
-  2. **自動定名更名**：使用 `git mv` 將目錄重命名為 `project/REQ-006-cart-checkout`，並將目錄內所有檔案的 `{{REQ_ID}}` 批次置換為 `REQ-006`。
-  3. **自動建立本機提交**：在 feature 分支自動建立 commit `docs(REQ-006): cart-checkout - 規格確認歸檔`。
-  4. **自動合併至主分支**：自動切換至主分支（`git checkout master`），將 feature 分支自動合併回主分支（`git merge feat/cart-checkout`），並重新生成主分支的 `project/index.md`，保證主分支規格最新且永遠不衝突！
+  1. **先推分支至 Remote 並同步遠端**：若 Git 有設定 remote，先將目前分支推送至遠端並執行 `git fetch` 同步最新狀態。
+  2. **自動向主分支查詢並取得新號**：查詢 master/main（含遠端主分支）目前最大序號（例如最大是 `REQ-005`，自動領取最新號 `REQ-006`），避免號碼競爭。
+  3. **自動定名更名**：使用 `git mv` 將目錄重命名為 `project/REQ-006-cart-checkout`，並將目錄內所有檔案的 `{{REQ_ID}}` 批次置換為 `REQ-006`。
+  4. **自動建立提交並推送分支**：在 feature 分支自動建立 commit `docs(REQ-006): cart-checkout - 規格確認歸檔`，若有 remote 則同步推送至遠端。
+  5. **自動合併至主分支並推送至 Remote**：自動切換至主分支（`git checkout master`），將 feature 分支自動合併回主分支（`git merge feat/cart-checkout`），重新生成主分支的 `project/index.md`，若有 remote 則自動將主分支推送至遠端（`git push origin master`），保證主分支規格最新且永遠不衝突！
 * **方式 B（CLI 終端指令）**：
   ```bash
   sa-spec finalize --name cart-checkout
   ```
-  CLI 同樣會自動查詢主分支最新序號定號、置換佔位符、完成提交並自動合併回 master！若想保留在當前分支手動處理，可加上 `--no-merge` 參數。
+  CLI 同樣會先推分支至 remote、查詢主分支最新序號定號、置換佔位符、完成提交、自動合併回 master 並推送至 remote！若想保留在當前分支手動處理，可加上 `--no-merge` 參數。
 
 #### 4. 消除索引合併衝突（`sa-spec reindex`）
 `project/index.md` 改為由目錄動態生成的「衍生清單」，不再依賴脆弱的手動 append：
@@ -702,7 +727,7 @@ git status
 git log -1 --oneline
 ```
 
-若要推送到 remote，需要明確要求 AI 執行 push，或自行執行：
+若 Git 有設定 remote，AI 與 CLI 會在建立分支與歸檔合併時自動執行 `git push` 推送至遠端；若當時尚未設定 remote，事後也可手動執行：
 
 ```bash
 git push origin main
@@ -719,11 +744,21 @@ git push origin master
 - 未經使用者確認，不得標示為 `已審核`。
 - `spec:analyze` 發現衝突時不得產出最終文件，也不得修改既有需求文件。
 - `project/system-spec.md` 只能在 `spec:commit` 依使用者確認內容更新。
-- `spec:commit` 會自動建立本機 Git commit；remote push 需使用者明確要求或啟用 auto-push。
+- **鐵律**：只要 Git 有設定 remote，`scp` 與 `scc` 都會自動將分支與主分支推送至 remote。
 - 一次最多問 3 個待確認問題，優先詢問會影響範圍、資料、權限、API、DB 或驗收的問題。
 
 ## 更新紀錄
 
+### v0.2.7
+- **新增 Markdown 轉 PDF 指令（`spec:pdf` / `spd` / `sa-spec pdf`）與跨平台獨立安裝腳本**：
+  - **Markdown 轉 PDF 支援**：新增 AI 指令 `spec:pdf`（簡寫 `spd`）與 CLI 指令 `sa-spec pdf <target> [--split] [--output out.pdf]`（及 `--all`），支援單一 `.md` 轉換、需求目錄整包合併匯出成一份完整規格書 PDF，或加 `--split` 各檔獨立匯出。
+  - **跨平台獨立管理腳本**：新增 macOS / Linux（`install.sh`、`update.sh`、`uninstall.sh`）與 Windows（`install.bat`、`update.bat`、`uninstall.bat`）6 個獨立執行腳本，一鍵完成安裝、更新與解除安裝。
+
+### v0.2.6
+- **Git Remote 自動推送鐵律（Remote Auto-Push）**：
+  - **`scp` 建立分支自動推上遠端**：執行 `spec:propose`（`scp`）或 `sa-spec new --branch` 建立 feature 分支後，自動偵測是否有設定 Git remote；若有則立即將新分支推送至遠端（`git push -u <remote> feat/<name>`）。
+  - **`scc` 先推分支再領號與主分支自動推送**：執行 `spec:commit`（`scc`）或 `sa-spec finalize` 時，若有設定 Git remote，會**先將目前分支推送至 remote 並同步遠端狀態**，接著才查詢主分支（`master`/`main`）最新可用序號定號，完成 feature 分支提交與推送、自動合併回主分支後，**自動將主分支推送至 remote**。
+
 ### v0.2.5
 - **支援前端 UI 線框圖（PlantUML Salt Code-as-Wireframe）**：
   - **純文字代碼化線框圖**：在 `uml/` 目錄新增標準 `uml/wireframe.puml`，使用 PlantUML Salt 語法（`@startsalt ... @endsalt`）以純文字定義頁面排版、輸入欄位、選項與按鈕，可直接在 VS Code 渲染預覽，並可納入 Git 版本追蹤。

package/src/cli.js

@@ -1,6 +1,12 @@
 const fs = require("fs");
 const path = require("path");
 const { spawnSync } = require("child_process");
+const {
+  buildHtmlDocument,
+  convertMarkdownFileToPdf,
+  buildMergedRequirementMarkdown,
+  renderHtmlToPdf
+} = require("./pdf");
 
 const cwd = process.cwd();
 const rootDir = path.resolve(__dirname, "..");
@@ -38,6 +44,9 @@ function main() {
     case "template":
       runTemplate(args.slice(1));
       return;
+    case "pdf":
+      runPdf(args.slice(1));
+      return;
     case "version":
     case "--version":
     case "-v":
@@ -306,6 +315,12 @@ function createReqTemplate(args, label = "new") {
       } else {
         console.log(`提示: 分支切換略過 (${(branchRes.stderr || "").trim() || "可能是已有同名分支或未在 git 目錄"})`);
       }
+
+      const remote = getDefaultRemote();
+      const activeBranch = getCurrentBranch() || branchName;
+      if (remote && activeBranch) {
+        pushBranchToRemote(remote, activeBranch);
+      }
     }
 
     const reqDir = path.join("project", slug);
@@ -349,6 +364,32 @@ function createReqTemplate(args, label = "new") {
   printResultList(label, results);
 }
 
+function getDefaultRemote() {
+  const res = spawnSync("git", ["remote"], { cwd, encoding: "utf8" });
+  if (res.status === 0 && res.stdout) {
+    const remotes = res.stdout
+      .split("\n")
+      .map((r) => r.trim())
+      .filter(Boolean);
+    if (remotes.includes("origin")) return "origin";
+    if (remotes.length > 0) return remotes[0];
+  }
+  return null;
+}
+
+function pushBranchToRemote(remote, branch) {
+  if (!remote || !branch) return false;
+  console.log(`[Git] 偵測到遠端 (${remote})，正在將分支 ${branch} 推送至 ${remote}/${branch}...`);
+  const pushRes = spawnSync("git", ["push", "-u", remote, branch], { cwd, encoding: "utf8" });
+  if (pushRes.status === 0) {
+    console.log(`[Git] 已成功將分支 ${branch} 推送至 ${remote}/${branch}`);
+    return true;
+  } else {
+    console.warn(`[Git 警告] 推送分支 ${branch} 至 ${remote} 失敗: ${(pushRes.stderr || pushRes.stdout || "").trim()}`);
+    return false;
+  }
+}
+
 function detectMainBranch() {
   const branches = ["main", "master"];
   for (const b of branches) {
@@ -367,7 +408,7 @@ function getCurrentBranch() {
   return null;
 }
 
-function getLatestMaxReqId(projectDir, mainBranch) {
+function getLatestMaxReqId(projectDir, mainBranch, remoteName = "origin") {
   let maxIdNum = 0;
   // 1. 掃描本地工作目錄既有 REQ-xxx
   if (fs.existsSync(projectDir)) {
@@ -400,7 +441,8 @@ function getLatestMaxReqId(projectDir, mainBranch) {
     }
 
     // 3. 掃描遠端主分支 (若有設定 remote)
-    const gitRemoteLs = spawnSync("git", ["ls-tree", `origin/${mainBranch}:project`], { cwd, encoding: "utf8" });
+    const targetRemote = remoteName || "origin";
+    const gitRemoteLs = spawnSync("git", ["ls-tree", `${targetRemote}/${mainBranch}:project`], { cwd, encoding: "utf8" });
     if (gitRemoteLs.status === 0 && gitRemoteLs.stdout) {
       for (const line of gitRemoteLs.stdout.split("\n")) {
         const parts = line.split("\t");
@@ -464,10 +506,17 @@ function finalizeReq(args) {
     return;
   }
 
-  // 1. 自動向本地與主分支查詢最新已使用的最大 REQ 序號
+  // 1. 先檢查是否有 remote，若有則先將目前分支推上 remote 並同步遠端狀態，接著才查詢主分支最新 REQ 序號
+  const remote = getDefaultRemote();
   const mainBranch = detectMainBranch();
   const currentBranch = getCurrentBranch();
-  const maxIdNum = getLatestMaxReqId(projectDir, mainBranch);
+
+  if (remote && currentBranch) {
+    pushBranchToRemote(remote, currentBranch);
+    spawnSync("git", ["fetch", remote], { cwd, encoding: "utf8" });
+  }
+
+  const maxIdNum = getLatestMaxReqId(projectDir, mainBranch, remote);
 
   const nextIdNum = maxIdNum + 1;
   const nextId = `REQ-${String(nextIdNum).padStart(3, "0")}`;
@@ -518,14 +567,17 @@ function finalizeReq(args) {
 
   console.log(`\n 需求已成功定號歸檔為: ${nextId} (${finalDirName})`);
 
-  // 5. 自動提交與自動合併回主分支 (Git-Flow 閉環)
+  // 5. 自動提交、自動合併回主分支與自動推送至 remote (Git-Flow 閉環)
   const shouldAutoMerge = !args.includes("--no-merge");
   if (currentBranch && mainBranch && currentBranch !== mainBranch) {
     console.log(`[Git] 正在為分支 ${currentBranch} 建立歸檔 commit...`);
     spawnSync("git", ["add", "project/"], { cwd, encoding: "utf8" });
-    const commitRes = spawnSync("git", ["commit", "-m", `docs(${nextId}): ${name} - 規格確認歸檔`], { cwd, encoding: "utf8" });
+    const commitRes = spawnSync("git", ["commit", "-m", `docs(${nextId}): ${rawName} - 規格確認歸檔`], { cwd, encoding: "utf8" });
     if (commitRes.status === 0) {
-      console.log(`[Git] 分支 ${currentBranch} 提交完成: docs(${nextId}): ${name} - 規格確認歸檔`);
+      console.log(`[Git] 分支 ${currentBranch} 提交完成: docs(${nextId}): ${rawName} - 規格確認歸檔`);
+    }
+    if (remote) {
+      pushBranchToRemote(remote, currentBranch);
     }
 
     if (shouldAutoMerge) {
@@ -546,7 +598,10 @@ function finalizeReq(args) {
           spawnSync("git", ["add", "project/index.md"], { cwd, encoding: "utf8" });
           spawnSync("git", ["commit", "-m", `chore: update project/index.md for ${nextId}`], { cwd, encoding: "utf8" });
         }
-        console.log(` 全部歸檔流程完成！已自動領取新號 ${nextId} 並自動合併回主分支 ${mainBranch}。`);
+        if (remote) {
+          pushBranchToRemote(remote, mainBranch);
+        }
+        console.log(` 全部歸檔流程完成！已自動領取新號 ${nextId} 並自動合併回主分支 ${mainBranch}${remote ? ` 且推送至 ${remote}` : ""}。`);
       } else {
         console.error(`[Git 警告] 合併至 ${mainBranch} 發生衝突，請手動確認衝突狀況：\n${(mergeRes.stderr || mergeRes.stdout || "").trim()}`);
       }
@@ -556,12 +611,15 @@ function finalizeReq(args) {
     }
   } else if (currentBranch && currentBranch === mainBranch) {
     spawnSync("git", ["add", "project/"], { cwd, encoding: "utf8" });
-    spawnSync("git", ["commit", "-m", `docs(${nextId}): ${name} - 規格確認歸檔`], { cwd, encoding: "utf8" });
+    spawnSync("git", ["commit", "-m", `docs(${nextId}): ${rawName} - 規格確認歸檔`], { cwd, encoding: "utf8" });
     console.log(`[Git] 已直接於主分支 ${mainBranch} 建立提交完成。`);
+    if (remote) {
+      pushBranchToRemote(remote, mainBranch);
+    }
   } else {
     console.log(`建議接下來執行：`);
     console.log(`  git add project/`);
-    console.log(`  git commit -m "docs(${nextId}): ${name} - 規格確認歸檔"`);
+    console.log(`  git commit -m "docs(${nextId}): ${rawName} - 規格確認歸檔"`);
   }
 }
 
@@ -972,6 +1030,171 @@ function printResultList(label, results) {
   }
 }
 
+function resolveReqTargetDir(target) {
+  const directAbs = path.resolve(cwd, target);
+  if (fs.existsSync(directAbs) && fs.statSync(directAbs).isDirectory()) {
+    return directAbs;
+  }
+
+  const projectDir = path.join(cwd, "project");
+  if (!fs.existsSync(projectDir)) return null;
+
+  const inProjectAbs = path.join(projectDir, target);
+  if (fs.existsSync(inProjectAbs) && fs.statSync(inProjectAbs).isDirectory()) {
+    return inProjectAbs;
+  }
+
+  const norm = target.toLowerCase().trim();
+  const entries = fs.readdirSync(projectDir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const nameLower = entry.name.toLowerCase();
+    if (
+      nameLower === norm ||
+      nameLower.startsWith(`${norm}-`) ||
+      nameLower.endsWith(`-${slugify(target)}`)
+    ) {
+      return path.join(projectDir, entry.name);
+    }
+  }
+  return null;
+}
+
+function exportReqDirToPdf(reqAbsDir, options = {}) {
+  const { split = false, output = null, browser = null } = options;
+  const relDir = path.relative(cwd, reqAbsDir) || path.basename(reqAbsDir);
+  const results = [];
+
+  if (split) {
+    const entries = fs.readdirSync(reqAbsDir, { withFileTypes: true });
+    const mdFiles = entries
+      .filter((e) => e.isFile() && e.name.toLowerCase().endsWith(".md"))
+      .map((e) => path.join(reqAbsDir, e.name));
+
+    for (const mdFile of mdFiles) {
+      const res = convertMarkdownFileToPdf(mdFile, null, browser);
+      const relPdf = path.relative(cwd, mdFile.replace(/\.md$/i, ".pdf"));
+      if (res.ok) {
+        results.push({ action: "create", target: relPdf, message: `由 ${path.relative(cwd, mdFile)} 轉換 (${res.engine})` });
+      } else {
+        results.push({ action: "warn", target: relPdf, message: res.error });
+      }
+    }
+    return results;
+  }
+
+  const merged = buildMergedRequirementMarkdown(reqAbsDir);
+  if (!merged.markdown.trim()) {
+    results.push({ action: "warn", target: relDir, message: "目錄內無可匯出的規格文件內容" });
+    return results;
+  }
+
+  const defaultPdfPath = path.join(reqAbsDir, `${path.basename(reqAbsDir)}.pdf`);
+  const targetPdfPath = output ? path.resolve(cwd, output) : defaultPdfPath;
+  const html = buildHtmlDocument(merged.title, merged.markdown);
+  const res = renderHtmlToPdf(html, targetPdfPath, browser);
+  const relPdf = path.relative(cwd, targetPdfPath);
+
+  if (res.ok) {
+    results.push({
+      action: "create",
+      target: relPdf,
+      message: `已整包合併匯出完整需求規格書 PDF (${res.engine})`
+    });
+  } else {
+    results.push({ action: "warn", target: relPdf, message: res.error });
+  }
+  return results;
+}
+
+function runPdf(args = []) {
+  const split = args.includes("--split");
+  const all = args.includes("--all");
+  const output = getOption(args, "--output") || getOption(args, "-o");
+  const browser = getOption(args, "--browser");
+
+  const positional = [];
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === "--output" || a === "-o" || a === "--browser" || a === "--name" || a === "--target") {
+      i++;
+      continue;
+    }
+    if (a.startsWith("-")) continue;
+    positional.push(a);
+  }
+
+  const target = getOption(args, "--name") || getOption(args, "--target") || positional[0];
+
+  if (!target && !all) {
+    fail(
+      "Usage:\n  sa-spec pdf <file.md> [--output out.pdf]\n  sa-spec pdf <REQ-001|name|dir> [--split] [--output out.pdf]\n  sa-spec pdf --all [--split]"
+    );
+    return;
+  }
+
+  const results = [];
+
+  if (all) {
+    const projectDir = path.join(cwd, "project");
+    if (!fs.existsSync(projectDir)) {
+      fail("找不到 project/ 目錄。");
+      return;
+    }
+    for (const rootMd of ["system-spec.md", "index.md"]) {
+      const mdPath = path.join(projectDir, rootMd);
+      if (fs.existsSync(mdPath)) {
+        const res = convertMarkdownFileToPdf(mdPath, null, browser);
+        const relPdf = path.relative(cwd, mdPath.replace(/\.md$/i, ".pdf"));
+        results.push(
+          res.ok
+            ? { action: "create", target: relPdf, message: `已轉換 (${res.engine})` }
+            : { action: "warn", target: relPdf, message: res.error }
+        );
+      }
+    }
+    const entries = fs.readdirSync(projectDir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        const reqDir = path.join(projectDir, entry.name);
+        results.push(...exportReqDirToPdf(reqDir, { split, browser }));
+      }
+    }
+    printResultList("pdf", results);
+    return;
+  }
+
+  // 1. Check if target is a single .md file
+  const directFileAbs = path.resolve(cwd, target);
+  if (fs.existsSync(directFileAbs) && fs.statSync(directFileAbs).isFile()) {
+    const res = convertMarkdownFileToPdf(directFileAbs, output, browser);
+    const targetPdf = output
+      ? path.relative(cwd, path.resolve(cwd, output))
+      : path.relative(cwd, directFileAbs.replace(/\.[^.]+$/, ".pdf"));
+    if (res.ok) {
+      results.push({ action: "create", target: targetPdf, message: `單檔轉換完成 (${res.engine})` });
+    } else {
+      results.push({ action: "warn", target: targetPdf, message: res.error });
+      process.exitCode = 1;
+    }
+    printResultList("pdf", results);
+    return;
+  }
+
+  // 2. Check if target resolves to a requirement directory
+  const reqDirAbs = resolveReqTargetDir(target);
+  if (reqDirAbs) {
+    results.push(...exportReqDirToPdf(reqDirAbs, { split, output, browser }));
+    if (results.some((r) => r.action === "warn")) {
+      process.exitCode = 1;
+    }
+    printResultList("pdf", results);
+    return;
+  }
+
+  fail(`找不到指定的 Markdown 檔案或需求目錄: ${target}`);
+}
+
 function showHelp() {
   console.log(`sa-spec
 
@@ -979,6 +1202,8 @@ Usage:
   sa-spec init [--full] [--lang zh-TW|en|zh-CN|ja|ko]
   sa-spec new [--id REQ-001] --name login [--branch]
   sa-spec finalize --name login [--no-merge]
+  sa-spec pdf <file.md|REQ-001|name> [--split] [--output out.pdf]
+  sa-spec pdf --all [--split]
   sa-spec reindex
   sa-spec check
   sa-spec upgrade [--dry-run]