@loviusc/sa-spec 0.2.6 → 0.2.7

package/templates/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。 |
 
 狀態機：
 
@@ -725,6 +749,11 @@ git push origin master
 
 ## 更新紀錄
 
+### 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>`）。

package/templates/skills/system-analysis/SKILL.md

@@ -16,7 +16,7 @@ description: 用 init、propose、analyze、commit 四段流程整理需求，
 
 ## 指令流程
 
-使用四個核心指令，並支援簡寫別名（兩者等價）：
+使用五個核心指令，並支援簡寫別名（兩者等價）：
 
 | 指令 | 簡寫 | 用途 | 執行規則 |
 |---|---|---|---|
@@ -24,6 +24,7 @@ description: 用 init、propose、analyze、commit 四段流程整理需求，
 | `spec:propose` | `scp` | 提出需求 | 使用者提出需求後，自動依需求名稱建立並切換至專屬 feature 分支（`feat/<name>`，若已在 feature branch 則沿用），檢查是否有設定 Git remote，若有則自動將分支推上 remote（`git push -u <remote> feat/<name>`），並建立草稿目錄（內部使用 `{{REQ_ID}}` 佔位），整理需求摘要、目標、初步流程與待確認事項；不歸檔、不修改既有需求。 |
 | `spec:analyze` | `sca` | 分析與起草 | 先檢查新需求是否與 `project/` 內所有既有需求衝突；無衝突才產出 SRS、UML、OpenAPI、DB Schema 草稿；有衝突則只列出衝突與待釐清問題，待使用者釐清後再次執行 `spec:analyze`（或 `sca`）。 |
 | `spec:commit` | `scc` | 確認歸檔 | 只把使用者已確認的版本歸檔到該需求資料夾；若有 Git remote 則先將目前分支推上 remote 並同步遠端狀態，接著才查詢主分支（`master`/`main`）最新可用序號定號（`REQ-xxx`）、替換佔位符，更新 `project/index.md`、`project/system-spec.md` 與 `history.md`，建立 Git commit（若有 remote 則推送分支），再自動切換回主分支完成合併並推送到 remote。 |
+| `spec:pdf` | `spd` | 匯出 PDF | 呼叫 `sa-spec pdf <target> [--split] [--output <path>]`（或 `--all`），將指定的單一 `.md` 檔轉為同名 `.pdf`，或將指定需求目錄/編號（如 `REQ-001`）整包合併匯出成一份完整規格書 PDF（加 `--split` 則各別轉為獨立 PDF）。 |
 
 ## 硬性限制
 

package/uninstall.bat

@@ -0,0 +1,22 @@
+@echo off
+setlocal EnableDelayedExpansion
+chcp 65001 >nul 2>&1
+
+set "PACKAGE_NAME=@loviusc/sa-spec"
+set "SCRIPT_DIR=%~dp0"
+
+echo [sa-spec] 開始解除安裝 (Windows)...
+
+if exist "%SCRIPT_DIR%package.json" (
+    findstr /C:"@loviusc/sa-spec" "%SCRIPT_DIR%package.json" >nul 2>&1
+    if !errorlevel! equ 0 (
+        pushd "%SCRIPT_DIR%"
+        call npm unlink -g >nul 2>&1
+        popd
+    )
+)
+
+call npm uninstall -g %PACKAGE_NAME%
+
+echo [完成] 已解除安裝 sa-spec！
+pause

package/uninstall.sh

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+set -e
+
+PACKAGE_NAME="@loviusc/sa-spec"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+echo "[sa-spec] 開始解除安裝 (${OSTYPE:-macOS/Linux})..."
+
+if [ -f "${SCRIPT_DIR}/package.json" ] && grep -q '"@loviusc/sa-spec"' "${SCRIPT_DIR}/package.json" 2>/dev/null; then
+  (cd "${SCRIPT_DIR}" && npm unlink -g 2>/dev/null) || true
+fi
+
+npm uninstall -g "${PACKAGE_NAME}" || true
+
+echo "[完成] 已解除安裝 sa-spec！"

package/update.bat

@@ -0,0 +1,43 @@
+@echo off
+setlocal EnableDelayedExpansion
+chcp 65001 >nul 2>&1
+
+set "PACKAGE_NAME=@loviusc/sa-spec"
+set "SCRIPT_DIR=%~dp0"
+
+echo [sa-spec] 開始更新 (Windows)...
+
+where node >nul 2>&1
+if %errorlevel% neq 0 (
+    echo [錯誤] 未偵測到 Node.js，請先執行 install.bat。
+    pause
+    exit /b 1
+)
+
+set "IS_SOURCE=0"
+if exist "%SCRIPT_DIR%package.json" (
+    findstr /C:"@loviusc/sa-spec" "%SCRIPT_DIR%package.json" >nul 2>&1
+    if !errorlevel! equ 0 set "IS_SOURCE=1"
+)
+
+if "%IS_SOURCE%"=="1" (
+    echo [更新] 偵測到 sa-spec 原始碼目錄...
+    pushd "%SCRIPT_DIR%"
+    if exist ".git" (
+        where git >nul 2>&1
+        if !errorlevel! equ 0 (
+            echo [Git] 正在拉取最新原始碼 ^(git pull --ff-only^)...
+            git pull --ff-only
+        )
+    )
+    call npm install
+    call npm link
+    popd
+) else (
+    echo [更新] 從 npm 更新 %PACKAGE_NAME%@latest...
+    call npm install -g %PACKAGE_NAME%@latest
+)
+
+echo [完成] sa-spec 已更新至最新版本！
+call sa-spec --version 2>nul
+pause

package/update.sh

@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+set -e
+
+PACKAGE_NAME="@loviusc/sa-spec"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+echo "[sa-spec] 開始更新 (${OSTYPE:-macOS/Linux})..."
+
+if ! command -v node >/dev/null 2>&1 || ! command -v npm >/dev/null 2>&1; then
+  echo "[錯誤] 未偵測到 Node.js 或 npm，請先執行 ./install.sh。"
+  exit 1
+fi
+
+if [ -f "${SCRIPT_DIR}/package.json" ] && grep -q '"@loviusc/sa-spec"' "${SCRIPT_DIR}/package.json" 2>/dev/null; then
+  echo "[更新] 偵測到 sa-spec 原始碼目錄 (${SCRIPT_DIR})..."
+  if [ -d "${SCRIPT_DIR}/.git" ] && command -v git >/dev/null 2>&1; then
+    if (cd "${SCRIPT_DIR}" && git remote | grep -q .); then
+      echo "[Git] 拉取最新原始碼 (git pull --ff-only)..."
+      (cd "${SCRIPT_DIR}" && git pull --ff-only) || echo "[提示] git pull 略過，請確認本地是否有未提交修改。"
+    fi
+  fi
+  cd "${SCRIPT_DIR}"
+  npm install
+  npm link
+else
+  echo "[更新] 從 npm 更新 ${PACKAGE_NAME}@latest..."
+  npm install -g "${PACKAGE_NAME}@latest"
+fi
+
+echo "[完成] sa-spec 已更新至最新版本: $(sa-spec --version 2>/dev/null || echo '未知')"